CodeConventions.md

Code Conventions IntelliDoc

Formatierung:

• Einrückung mit Tabs: Benutze für die Einrückung des Codes Tabs und keine Leerzeichen.

• Kein Whitespace: Säubere vor jedem Commit alle nachfolgenden Leerzeichen im Code.

• Semikolons: Verwende im Code konsequent Semikolons, um die Lesbarkeit und Wartbarkeit des Codes zu gewährleisten.

• Zeilenlänge von 80: Halte dich an eine Zeilenlänge von maximal 80 Zeichen für bessere Lesbarkeit

• Doppelte Anführungszeichen verwenden:
  

  Richtig:
  

  var foo = "bar;"

  Falsch:

  var foo = 'bar';

• Setze geschweifte Klammern in stets in dieselbe Zeile
  Richtig:

if (true) {
  console.log('winning');
}

Falsch:

if (true)
{
  console.log('losing');
}

• Deklariere pro var-Anweisung eine Variable. Dadurch wird es einfacher, die Zeilen neu anzuordnen.
  

  Richtig:

var keys   = ['foo', 'bar'];
var valuesOf... = [23, 42];
var ...Object = {};

Falsch:

var keys = ['foo', 'bar'],
       values = [23, 42],
       object = {};

Namenskonventionen

• Verwende lowerCamelCase für Variablen, Properties und Funktionsnamen. Die Namen sollten außerdem beschreibend sein, einzelzeichen-Variablen und unübliche Abkürzungen sollten grundsätzlich vermieden werden.
  Richtig:

var selectAdminUser = db.query('SELECT * FROM users ...');

Falsch:

var user = db.query('SELECT * FROM users ...');

• Klassennamen sollten mit UpperCamelCase geschrieben und großgeschrieben werden.
  Richtig:

function BankAccount() {…}

Falsch:

function bank_Account() {…}

Kommentare

• Kommentare sollten nur hinzugefügt werden, wenn sie unerlässlich sind. Nach Absprache zur automatischen Dokumentation TypeDoc verwenden.
• Blockkommentare sind auf gleicher Einrückungsebene wie der umgebende Code. Sie können im Stil /* ... / oder // ... verwendet werden. Bei mehrzeiligen / ... / Kommentaren müssen nachfolgende Zeilen mit einem * beginnen, das mit dem * auf der vorherigen Zeile ausgerichtet ist. Beispiele: /

• Das ist // Und das /* Oder auch
• erlaubt // hier auch. * sowas. //

Autoren

Autoren müssen in jeder Klasse mit dem Tag '@Author' markiert werden.

Refactoring

• Um den Code lesbar zu halten, soll der Code vor allem vor einer Feature Implementierung refaktoriert werden.
  Zum Refactoring gehören:
  • Variablen/Methodennamen den Konventionen entsprechend umbenennen
  • Unnötige Variablen entfernen
  • Code extrahieren
  • Code ersetzen

Variablen/Methodennamen umbenennen

Vor dem Refactoring:

String[] name = {Henning Ahlf, Kolja Dunkel};

Nach dem Refactoring:

int[] profNameArray = {Henning Ahlf, Kolja Dunkel};

Unnötige Variablen entfernen

Vor dem Refactoring:

String helloWorld = "Hello World";
System.out.println(helloWorld);

Nach dem Refactoring:

System.out.println("Hello World");

Code extrahieren

Vor dem Refactoring:

public static String gibFarbe(int wert) {
        int teilwert = 255 / (farben.length - 1);
        String s = farben[(int) (((double) wert / (double) teilwert) + 0.5];
    }

Nach dem Refactoring:

public static String gibFarbe(int wert) {
        int teilwert = 255 / (farbArrayLaenge() - 1);
        String s = farben[calcIndexMitRundung(wert, teilwert)];
    }
 
 private static int farbArrayLaenge() {
            return farben.length;
    }

private static int calcIndexMitRundung(int wert, int teilwert) {
            return (int) (
                    ((double) wert / (double) teilwert)
                            + 0.5
                );
    }

Code ersetzen

Vor dem Refactoring:

double basePrice = quantity * itemPrice;
double discountFactor;
if(basePrice > 1000) { discountFactor = 0.95; } else { discountFactor = 0.98;
double price = basePrice * discountFactor;

Nach dem Refactoring;

double price = quantity * itemPrice
                        * ((quantity * itemPrice > 1000) ? 0.95
                                                          : 0.98);

Richtiger Beispielcode (in Java) nach den Konventionen

public class ImageToASCIITest {
    /**
     * Eine Klasse, die eine Idee zur Konvertierung von Farbwerten in bestimmte ASCII Zeichen testet.
     */

    private static String[] farben = new String[]{"weiß", "rot", "blau", "grün", "lila", "gelb", "schwwarz", "magenta", "rosagepunktet"};

    public static String gibFarbe(int farbWert) {
        int teilwert = 255 / (farbArrayLaenge() - 1);
        String s = farben[calcIndexMitRundung(farbWert, teilwert)];

        //printKontrollwert(farbWert);
        return wert + "\t\t" + s;
    }

    private static int farbArrayLaenge() {
            return farben.length;
    }

    private static int calcIndexMitRundung(int farbWert, int teilwert) {
            return (int) (
                    ((double) farbWert / (double) teilwert)
                            + 0.5
                );
    }

    private static void printKontrollwert(int farbWert) {
        System.out.println("\nWert:\t" + farbWert);
    }

    public static void main(String[] args) {
        /**
         * Mit einem Eingabewert soll ein entsprechender Index in einem Array berechnet und dessen
         * Inhalt ausgegeben werden
         *
         * Farbwert [0, 255]
         */

        for (int i = 0; i < 255; i++) {
            System.out.println(gibFarbe(i));
        }
    }
}