BZZ - Codingstandards

Bezeichner sind die «Namen» von Klassen, Methoden, Attributen, Variablen und Konstanten.

Ein sprechender Bezeichner sagt etwas über den Sinn und Zweck einer Komponente aus. Durch den Einsatz von sprechenden Bezeichnern werden viele Kommentare überflüssig.

	Die Bezeichner (Namen) von Klassen, Methoden, Attributen, Variablen und Konstanten müssen sprechend sein.
	Schleifenzähler innerhalb einer kurzen Iteration (max. 5 Zeilen) dürfen auch kürzere Variablennamen wie i, j verwenden.

public class category {
 
    String[] categories = {"Getränke", "Vorspeisen", "Hauptgang", "Dessert"};public class Project {
    private String projectTitle;
    private static final int NUMBER = 10;
 
    /**
     * @param projectTitle
     *            the projectTitle to set
     */
    public void setProjectTitle(String projectTitle) {
        this.projectTitle = projectTitle;
    }
 
}
    public int readCategoryByTitle(String categoryTitle) {
        int categoryId = -1;
 
        for (int i=0; i < categories.length; i++) {
            if (categories[i].equals(categoryTitle)) {
                categoryId = i;
            }
        } 
 
        return categoryId;
    }
}

Durch eine einheitliche Schreibweise verbessern Sie die Lesbarkeit Ihres Sourcecodes.

	Klassennamen bestehen aus einem Substantiv und beginnen mit einem Grossbuchstaben (z.B. Account).
	Die Bezeichner von Methoden, Attributen und Variablen beginnen mit einem Kleinbuchstaben.
	Konstanten werden nur mit Grossbuchstaben geschrieben.
	Zusammengesetzte Bezeichner sollten in camelCase geschrieben werden; z.B. getFirstname().
	Vermeide Sonderzeichen, Leerzeichen und Umlaute in allen Bezeichnern, sowie in Datei- und Ordnernamen.

public class Project {
    private String projectTitle;
    private static final int NUMBER = 10;
 
    /**
     * @param projectTitle
     *            the projectTitle to set
     */
    public void setProjectTitle(String projectTitle) {
        this.projectTitle = projectTitle;
    }
}

Der Einsatz von public-Attributen untergräbt das Prinzip der Datenkapselung.

Die Attribute einer Klasse werden entweder private (Normalfall) oder protected (Vererbung) definiert.

Die konsequente Verwendung von getter/setter-Methoden unterstützt lazy initialization und vermeidet Konflikte mit lokalen Variablen.

Der Zugriff auf Attribute soll auch in derselben Klasse mittels Getter/Setter-Methoden erfolgen.

public class Project {
    private String projectTitle;
    private Category category;
    private static final int NUMBER = 10;
 
    /**
      * default constructor
      */
    public Project() {
        setProjectTitle(“”);
        setCategory(new Category());
    }
 
    /**
     * @param projectTitle
     *            the projectTitle to set
     */
    public void setProjectTitle(String projectTitle) {
        this.projectTitle = projectTitle;
    }
 
    /**
      * @param category
      *           the category to set
      */
    public void setCategory(Category category) {
        this.category = category;
    }
}

Eine klare und einheitliche Programmierung erleichtert das Lesen eines Sourcecodes.

Ein Programmblock wird zwischen geschweiften Klammern { … } eingefasst.

	Die Positionierung der geschweiften Klammern ist einheitlich innerhalb des ganzen Projekts.
	Innerhalb eines Programmblocks werden die Zeilen um 2 oder 4 Stellen eingerückt. Die Einrückung ist im ganzen Sourcecode einheitlich.

    if (anredeCode == 1) {
        return "Herr";
    } else {
        return "Frau";
    }
 
    try {
         ...
    } catch (...) {
        ...
    }

    if (anredeCode == 1) 
    {
        return "Herr";
    } 
    else 
    {
        return "Frau";
    }
 
    try 
    {
         ...
    } 
    catch (...) 
    {
        ...
    }

Eine Codezeile sollte immer auf einen Blick erfasst werden können.

	Eine Codezeile ist maximal 80 (oder 120) Zeichen lang. Längere Zeilen werden umgebrochen.
	Ordnen Sie gleiche Elemente wie Bezeichner oder Bedingungen untereinander an.

if ( 
     ( Integer.parseInt(eingabeMenge) >= mindestMenge  && 
       Integer.parseInt(eingabeMenge) <= maximalMenge
     ) || 
     ( kunde.kundenArt.equals("Stammkunde") && 
       Integer.parseInt(eingabeMenge) > 0
     ) 
   ) {
    ....
}

Konstruktoren versetzen ein neu erzeugtes Objekt in einen definierten Anfangszustand.

	Die Konstruktor-Methode(n) stehen an erster Stelle, um die Übersichtlichkeit zu erhöhen.
	Die Initialisierung von Attributen erfolgt im Konstruktor, nicht bei der Deklaration.

public class Project {
    private String projectTitle;
    private Category category;
 
    /**
      * default constructor
      */
    public Project() {
        setProjectTitle(“”);
        setCategory(new Category());
    }
 
...
}

Durch eine geeignete Reihenfolge fällt es leichter, die richtige Methode effizient zu finden.

Ähnliche Methoden sollen immer in der gleichen Reihenfolge angeordnet werden.

1. Konstruktoren
   1. Default constructor
   2. Alternative Konstruktoren
2. Methoden die eine Verarbeitung auslösen (z.B. savePerson())
3. Methoden die auf ein Ereignis reagieren (Listener, Events)
4. Getter/Setter-Methoden
   1. Getter/Setter mit integrierter Logik
   2. «Normale» Getter/Setter die Attribute 1 zu 1 lesen oder schreiben.

Zur Dokumentation des Sourcecodes verwenden wir Javadoc-Kommentare. Dadurch ersparen wir uns eine separate Beschreibung der Klassen und Methoden in einem Textdokument.

Der Klassenkopf ist die Visitenkarte einer Klasse. Er informiert den Programmierer über Aufgabe und Version dieser Klasse.

	Jede Klasse hat einen Javadoc-Klassenkopf. Dieser enthält mindestens die Angaben zu: * Kurzbeschreibung * @author: Autor(en)
	Sofern Sie keine Versionsverwaltung (z.B. git) verwenden, sollten ausserdem * @since: Letztes Änderungsdatum * @version: Aktuelle Version des Sourcecodes im Kopf stehen.

/**
 * category to which a project is assigned
 *
 * @author Marcel Suter
 * @since 2017-09-19
 * @version 1.0
 *
 */

Der Methodenkopf liefert alle Angaben über die Aufgabe und Schnittstelle einer Methode.

Jede Methode hat einen Javadoc-Kopf mit den Angaben: * Kurzbeschreibung * @param: Beschreibung der Parameter (falls vorhanden) * @return: Beschreibung des Returnwerts (falls vorhanden) * @exception: Beschreibung der Exceptions (falls vorhanden)

/**
  * load a project from the database
  * 
  * @param  projectId      the unique id of a project
  * @param  categoryTitle  the category title to be searched
  * @return enum Result
  * @throws Exception(“duplicate entry”)
  */

Kommentare sind wie das Salz in der Suppe: Zuwenig und es schmeckt nicht, zu viel und es ist ungeniessbar.

	Jeder Programmblock, dessen Aufgabe nicht offensichtlich ist, wird in einem Kommentar beschrieben.
	Ein kurzer Blockkommentar ist oftmals sinnvoller als Zeilenkommentare, die über den Bildschirm hinausreichen.

private Connector getConnector() {
    // create a new connector, if not exists
    // and establish connection if needed
    if (this.connector == null) {
        setConnector(new Connector());
    }
    if (this.connector.getHandle() == null) {
        this.connector.connect();
    }
    
    return this.connector;
}

© Kevin Maurizi, Marcel Suter, René Probst