Vorlage:Codingstyle

Zustand

Der Source der Neutrino Quellen ist zum größten Teil in C bzw C++ geschrieben. Da teilweise viele Personen an ein und derselben Datei gearbeitet haben kann es innerhalb ein und der selben Datei die unterschiedlichsten Formatierungen geben.
In den sonstigen Dateien wiederum (Shellscripte z.B.) gibt es keine besonderen Unterschiede in den Styles und Formatierungen.

Einrückung

Für das Formatieren von C/C++ gibt es leicht unterschiedliche Einrückungsstile. Um die Lesbarkeit des Quellcodes zu verbessern sollten Programmierer die in den diversen Dateien arbeiten sich an bestimmte Standards halten. Dies ist kein absolutes Muss, ist aber sehr zuträglich für das Tuxboxprojekt. In anderen GNU Projekten ist die Einhaltung projektspezifischer Standards wegen der Größe dieser Projekte wiederum Pflicht. So zum Beispiel bei der Linuxkernelentwicklung oder beim KDE Projekt.

Quelltextformatierungen

Da an Neutrino wohl fast nur Freiwillige arbeiten ist so eine Forderung wohl nicht umzusetzen. Man kann so etwas aber sehr wohl als erstrebenswertes Optimum ansehen und jeder der mitarbeitet sollte sich so weit es geht an solche Wunschvorgaben halten.

Als ein guter Kompromiss zwischen Lesbarkeit und Platzbedarf hat sich der Stil 1TBS/K&C („One True Brace Style“ von Kernighan und Ritchie) erwiesen. Kurz und kompakt bedeuted das folgendes:

• Die öffnende Klammer einer Funktion steht immer an einem Zeilenanfang.

int do_read (int para_one, int para_two)
{
...
}

• Im Gegensatz dazu steht die öffnende Klammer von Schleifen oder Wenn Dann Bedingen immer am Ende der Bedingung.

if(( hp = gethostbyname( host )) != NULL ){
       memmove( &taddr->sin_addr, hp->h_addr_list[0], sizeof( taddr->sin_addr ));
       taddr->sin_port = 0;
       taddr->sin_family = AF_INET;
 } else if( inet_aton( host, &taddr->sin_addr ) == 0 ){
       return -1;
 }

• Die Einrückungstiefe (Tabulator) sollte aus aus acht Zeichen bestehen. Vier Zeichen sind allerdings auch o.k. Innerhalb einer Datei sollte aber immer die selbe Einrückungstiefe benutzt werden.

• Hier ist zu beachten das je nach verwendeten Editor und dessen Einstellungen unterschiedliche Effekte auftreten können. Die meisten Editoren bieten an eine Tabeinrückung mit der entsprechenden Leerzeichenanzahl aufzufüllen. Kontrolliert Eure Einstellung im Editor.

Kommentare

• Kommentare sind wichtige Bestandteile des Quellcodes! Nutzt diese Möglichkeit der Information. Leider sind Kommentare sehr spärlich im Code. Es muss nicht jede Subroutine erklärt werden, ein Kommentar zu einer Funktion, der Funktionsweise und Rückgabewerte sollte aber selbstverständlich sein.

• In internationalen Projekten sind Kommentare in Landessprache des Entwickler verpönt! Üblich und eine von jeden Programmierer verstandene Sprache ist Englisch, also bitte alle Kommentare in Englisch verfassen.

• Kommentare über mehr wie eine Zeile sollten mit /* ... */ eingefasst und einzeilige Kommentare mit // begonnen werden. Kommentare sollten entweder der einzigste Inhalt einer Zeile sein oder am Ende einer Codezeile stehen aber niemals mitten im Code (was theoretisch auch geht).

/*
 * draw_line
 * 
 * args:
 * x1    StartCol
 * y1    StartRow
 * x2    EndCol
 * y1    EndRow
 * state LCD_PIXEL_OFF/LCD_PIXEL_ON/LCD_PIXEL_INV
 * 
 */

oder

        //open device
        if ((fd = open(LCD_DEVICE, O_RDWR)) < 0) {
                perror("LCD (" LCD_DEVICE ")"); // giving out an error message
        ...