Vorlage:Codingstyle

Der Sourcecode von Neutrino ist inzwischen in die Jahre gekommen. Viele Programmierer haben Hand am Source angelegt. Da es nie Maintainer oder besondere Sourcecode Formatierungsregeln gab, ist der Quellcode von Neutrino, und auch der daraus entstandene Quellcode von Neutrino-HD, in unterschiedlichster Weise formatiert. Dies ist für die Lesbarkeit und für das Verständnis des Quellcodes nicht von Vorteil.

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 Projekt. 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 nur schwer 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:

Beispiele

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

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;
}

• Im Gegensatz dazu hier das gleiche Beispiel kürzer, aber nicht so übersichtlich mit der öffnenden Klammer direkt nach der Bedingung von Schleifen, if...then...else...-Steuerpaaren usw. mit schließender Klammer vor der nächsten 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 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.
• Komplettes Verändern von Dateien, nur um die obigen Punkte zu erreichen (z.B. durch Tools wie astyle) ist aber unbedingt zu vermeiden! Dadurch geht die komplette History zu dieser Datei verloren. Es sollten daher nur die Stellen selektiv nebenher verändert werden, wo man gerade Veränderungen durchführen will.

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 einzige 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
        ...

Debugausgaben

Ausgabe von Debugmeldungen sind ein wichtiges Hilfsmittel bei der Entwicklung. Für den normalen Betrieb sind diese Debugausgaben jedoch auf die wichtigsten Meldungen zu minimieren. Gerade hier kann Neutrino-HD noch deutlich verbessert werden. Einfache printf Ausgaben sind für die eigene Entwicklung o.k. sollten aber nicht in ein Versionsverwaltungssystem eingecheckt werden.