Code strukturieren/lesbarer/übersichtlicher machen

[McMannus]

Hi@ll,

da ich im Moment ein verhältnismäßig unübersichtlichen Code habe, weil ich "einfach mal drauf los" gecodet habe, würde ich gerne mal wissen, welche Kriterien denn ein gut lesbarer/übersichtlicher Code erfüllen muss.

Der Hintergrund ist ganz simpel: Wenn ich für andere, die bedingt Ahnung von Flash/AS haben und etwas lernen möchten, bestimmte Programme erstelle, dann möchte ich klarerweise auch, dass sie einen möglichst guten Lerneffekt haben.

Im Einzelnen würde ich da gerne auf folgende Sachen eingehen:
-Kommentare
-Nomenklatur von Variablen/Funktionen
-Klammernsetzen bei Funktionen, onRelease etc.
-Bestimmte "Themen" zusammenfassen
-Leerzeilen nach Kontrollstrukturen

Kommentare: Inwieweit sollte man Code kommentieren? Ab welchem Grad stört das die Übersicht?

Nomenklatur: Was ist die sinnvollste Weise Variablen und Symbole zu benennen? (abgesehn davon, dass sie problembezogen sein sollen )

Klammern: Sollten die Klammern in jedem Fall in der Spalte mit der zugehörigen Kontrollstruktur sein und wie weit sollte man einrücken?

Themen: Sollte man die einzelenen Themen (z.B. Button Funktionen oder Funktionen eines bestimmten Themengebietes) eher chronologisch nach ihrer Benutzung oder eher nach Themengruppe zusammenfassen?

Leerzeilen: Wann sind Leerzeilen zwischen Kontrollstrukturen sinnvoll?

Ich weiß, dass es verschiedene Ansichten zu dem Thema gibt, aber im Hinblick darauf, dass vielleicht noch andere das Thema interessiert, hätte ich gerne mal eure Ansichten dazu gehört, dass ich mir nichts "falsches" angewöhne. Entschuldigt außerdem die Banalität und Naivität mancher Fragen, aber wenn man nicht bei Null anfängt, wirds auch nix

Danke für eure hoffentlich zahlreichen Antworten!

Grüße Jan

[Omega Psi]

Kommentare:

1. Zum einen Dokumentation von Funktionen und ihrer Argumente sowie Rückgabewerte. Im Code sollte nur nicht-trivaler Code Kommentiert werden, wenn es sich ein Projekt handelt. Bei Beispielen in der API Dokumentation der Code für das wesendliche:

   /**
    * Adds a new item to the underlaying collection.
    * @param item
    *        The item to add.
    * @return <code>true</code> if the item was added,
    * <code>false</code> else.
    */
   function addItem(item:Item):Boolean {
     try {
       this.items.push(item);
       return true;
     catch (error:Error) {
       return false;
     }
     return false;
   } 

2. Vernünftige Benennung von Variablen und Funktionen ihrer Aufgaben nach. Beispiele für vernünftige Funktionsnamen findest du Beispielsweise in den APIs von Sun und Adobe oder hier (einfach mal show source klicken)
3. Auch hier scheiden sich die Geister. Ich formatiere wie in dem erzeugten Quelltext der obigen Anwendung.
4. Ich habs in FLA immer alphabetisch gemacht. Wenn man objektorientiert codet muss man das nicht mit den entsprechenden Tools, ich mach's aber trotzdem, ist ein wenig aufgeräumter.
5. Ich habe nur zwischen Imports, Funktionen etc. Leerzeichen (sie Anwendung).