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 bedeutet das folgendes:

Beispiel Funktionsdeklaration

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

void usb_stor_pad12_command(struct scsi_cmnd *srb, struct us_data *us)
{
...
}

• Bei vielen Funktionsübergabeparametern sollten an diesen jeweils möglichst die Zeile umgebrochen werden. Eine Zeile sollte nicht mehr wie 72 Zeichen enthalten.

unsigned int usb_stor_access_xfer_buf(unsigned char *buffer,
	unsigned int buflen, struct scsi_cmnd *srb, struct scatterlist **sgptr,
	unsigned int *offset, enum xfer_buf_dir dir)
{
...
}

Beispiel Schleifen

• Schleifen können genauso eingefasst werden. Dies kostet aber relativ viel Platz bei zahlreichen einfachen Aktionen, darum folgende Empfehlung die öffnenden Klammer direkt nach der Bedingung von Schleifen, if...then...else...-Steuerpaaren usw. zu setzen mit der schließenden Klammer vor der nächsten Bedingung. Dieser Stil wird auch in der Kernelentwicklung angewandt und ist sehr gebräuchlich.

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

• Das Gegenstück dazu ist jede Klammer separat in eine Zeile zu setzen und ist aber eben auch möglich. Die Lesbarkeit des Quellcodes welcher logisch zusammen gehört wird dabie deutlich erhöht. Der selbe Quellcode würde dann so aussehen.

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

• Letztendlich gilt aber auch hier: Benutzt den Stil den Ihr in der Datei vorfindet!
• 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. Diese ist aber bei der Einkreisung von Programmierfehlern teilweise sehr hilfreich! 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 Informationweitergabe. Leider sind Kommentare aktuell sehr spärlich im Code. Es muss nicht jede Subroutine erklärt werden, ein Kommentar zu einer Funktion, der Funktionsweise und deren 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 können mit // begonnen werden, üblich ist aber auch wieder die Einfassung mit /* ... */. 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

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

folgendes ist auch gebräuchlich

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.