From 8b6830a26ed6129937079c897b1446d1bdf26afe Mon Sep 17 00:00:00 2001 From: Moritz Bunkus Date: Thu, 22 Sep 2005 08:58:40 +0000 Subject: [PATCH] =?utf8?q?Erweiterung=20der=20Programmierrichtlinien=20um?= =?utf8?q?=20Regeln=20f=C3=BCr=20den=20Inhalt=20und=20nicht=20nur=20f?= =?utf8?q?=C3=BCr=20die=20Optik.?= MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit --- doc/programmierstilrichtlinien.txt | 89 +++++++++++++++++++++++++++--- 1 file changed, 81 insertions(+), 8 deletions(-) diff --git a/doc/programmierstilrichtlinien.txt b/doc/programmierstilrichtlinien.txt index 8da0febb3..644e8f590 100644 --- a/doc/programmierstilrichtlinien.txt +++ b/doc/programmierstilrichtlinien.txt @@ -14,12 +14,77 @@ sind die dazugeh meisten Linux-Distributionen enthalten und kann ansonten unter http://perltidy.sourceforge.net heruntergeladen werden. -Jeder, der einen Patch schickt, sollte sein Script vorher durch perltidy -laufen lassen. Damit werden einige der nachfolgenden Regeln automatisch -befolgt, andere hingegen nicht. Dort, wo keine perltidy-Optionen angegeben -sind, muss der Programmierer selbst für die Einhaltung sorgen. +Jeder, der einen Patch schickt, sollte sein Script vorher durch +perltidy laufen lassen -- und seine Veränderung danach noch einmal +kurz testen! Damit werden einige der nachfolgenden Regeln automatisch +befolgt, andere hingegen nicht. Dort, wo keine perltidy-Optionen +angegeben sind, muss der Programmierer selbst für die Einhaltung +sorgen. --------------------------------------------------------------------------- +(A) "Inhalt" +============ + +1. Alle Variablen müssen in dem Block, in dem sie benutzt werden mit + "my $variable;" oder mit "local *FILEHANDLE;" deklariert werden. + Neue globale Variablen einzuführen ist nicht erlaubt! + +2. Variablennamen + + 2.1 Alle Variablennamen müssen sinnvoll sein. "$i" als Schleifenzähler zu + nehmen ist in Ordnung. Sobald es aber über einen trivialen Fall + hinausgeht ist der Variable ein Name zu geben, der den Inhalt wieder- + spiegelt. Beispielsweise "$rowcount" für die Anzahl der Zeilen/ + Positionen in einer Rechnung oder "$net_price" für den Nettopreis. + + 2.2 Variablen, die einfach den Inhalt einer Datenbankspalte beeinhalten, + sollten so benannt werden, wie die Datenbankspalte ebenfalls heißt. + + 2.3 Variablennamen sollten in Englisch gehalten sein, weil der Rest + des Programms ebenfalls in Englisch gehalten ist. Für Begriffe, + für die es keine englischen Entsprechungen gibt, sind deutsche + Variablennamen in Ordnung. + +3. Die Schreibweise von Variablen sollte komplett klein ein. Zusammengesetzte + Namen sollten mit Unterstrichen getrennt werden. Beispiel: "$net_price". + +4. Kommentare + + 4.1 Kommentare beziehen sich immer auf Code in der gleichen Zeile, wenn + der Kommentar am rechten Rand steht, oder auf den nachfolgen Code. + + 4.2 Codeteile, deren Funktion nicht auf den ersten Blick ersichtlich ist, + sollten kommentiert werden. Der Kommentar sollte kurz beschreiben, + was der Codeteil macht, eventuelle Nebenwirkungen oder Probleme + auflisten. + + 4.3 Kommentare der Art, dass Benutzer X am Datum Y den Teil Z geändert + hat, sind nicht notwendig. Dafür gibt es die SVN-Commit-Nachrichten, + die all diese Informationen enthalten bzw. enthalten müssen. + + 4.4 Funktionen sollten kommentiert werden. Dazu wird vor der Funktion + ein Kommentarblock erstellt, der beschreibt, was diese Funktion + tut. Zusätzlich sollte aufgezählt werden, welche Parameter die + Funktion erwartet und welche Bedeutung diese haben. Der Rückgabewert + ist ebenfalls zu dokumentieren. + +5. Alle Texte/Begriffe, die ausgegeben werden, müssen mit + $text->locale('Begriff'); ausgegeben werden, damit diese Begriffe + übersetzt werden können. Das betrifft aber nur Begriffe, die einzeln + übersetzbar sind, natürlich nicht für z.B. HTML-Code. + +6. Änderungen in den Kernbestandteilen von Lx-Office, die nur der Anbindung + von Modulen dienen, die wiederum nicht Bestandteil der offiziellen + Distribution sind, müssen durch eine Konfigurationsvariable abschaltbar + sein. Damit soll verhindert werden, dass solcher Code ausgeführt wird, + wenn das Modul nicht installiert ist, da dieser Code ausschließlich von + den Programmierern dieses Moduls getestet werden kann. + + + + + +(B) "Optik" -- Sachen, die die Form betreffen +============================================= 1. Es werden keine "echten" TAB-Zeichen sondern Leerzeichen verwendet. Perltidy: -nt @@ -116,7 +181,7 @@ sind, muss der Programmierer selbst f 8. Mehrzeilige Befehle 8.1 Werden die Parameter eines Funktionsaufrufes auf mehrere Zeilen - aufgeteilt, so m[ssen diese bis zu der Spalte eingerückt werden, + aufgeteilt, so müssen diese bis zu der Spalte eingerückt werden, in der die ersten Funktionsparameter in der ersten Zeile stehen. Perltidy: -lp -vt=1 -vtc=1 Beispiel: @@ -153,7 +218,7 @@ sind, muss der Programmierer selbst f $form->{"row_$i"} = $form->{"row_$i"} - 5; $some_hash{42} = 54; -11. Die Maximale Zeilenlänge ist nicht bescränkt. Zeilenlängen <= 79 +11. Die Maximale Zeilenlänge ist nicht beschränkt. Zeilenlängen <= 79 helfen, weil sie dann im Textmodus / per SSH deutlich besser lesbar sind. Oft genug ist es aber nicht möglich oder nur unter großen Verrenkungen, diese Vorgabe einzuhalten. @@ -161,7 +226,11 @@ sind, muss der Programmierer selbst f Zeilen sollten nicht länger als 79 Zeichen sein. Perltidy: -l=79 --------------------------------------------------------------------------- + + + +(C) Liste der perltidy-Optionen +=============================== Vollständige Liste aller Optionen, die ich für perltidy benutze. Diese können in ~/.perltidyrc geschrieben werden: @@ -195,3 +264,7 @@ k -lp -vt=1 -vtc=1 + + + + -- 2.20.1