Menu
▾
▴
[Lx-office-svn] [SVN: lx-office-erp] r544 - trunk/stable/doc
|
From: SVN c. m. <m.b...@li...> - 2005-09-22 08:59:30
|
Author: mbunkus Date: 2005-09-22 10:58:40 +0200 (Thu, 22 Sep 2005) New Revision: 544 Modified: trunk/stable/doc/programmierstilrichtlinien.txt Log: Erweiterung der Programmierrichtlinien um Regeln f?\195?\188r den Inhalt = und nicht nur f?\195?\188r die Optik. Modified: trunk/stable/doc/programmierstilrichtlinien.txt =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- trunk/stable/doc/programmierstilrichtlinien.txt 2005-09-22 07:24:46 U= TC (rev 543) +++ trunk/stable/doc/programmierstilrichtlinien.txt 2005-09-22 08:58:40 U= TC (rev 544) @@ -14,13 +14,78 @@ meisten Linux-Distributionen enthalten und kann ansonten unter http://perltidy.sourceforge.net heruntergeladen werden. =20 -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 angegeb= en -sind, muss der Programmierer selbst f=FCr die Einhaltung sorgen. +Jeder, der einen Patch schickt, sollte sein Script vorher durch +perltidy laufen lassen -- und seine Ver=E4nderung 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=FCr die Einhaltung +sorgen. =20 -------------------------------------------------------------------------= -- +(A) "Inhalt" +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 +1. Alle Variablen m=FCssen in dem Block, in dem sie benutzt werden mit + "my $variable;" oder mit "local *FILEHANDLE;" deklariert werden. + Neue globale Variablen einzuf=FChren ist nicht erlaubt! + +2. Variablennamen + + 2.1 Alle Variablennamen m=FCssen sinnvoll sein. "$i" als Schleifenz=E4= hler zu + nehmen ist in Ordnung. Sobald es aber =FCber einen trivialen Fall + hinausgeht ist der Variable ein Name zu geben, der den Inhalt wied= er- + spiegelt. Beispielsweise "$rowcount" f=FCr die Anzahl der Zeilen/ + Positionen in einer Rechnung oder "$net_price" f=FCr den Nettoprei= s. + + 2.2 Variablen, die einfach den Inhalt einer Datenbankspalte beeinhalte= n, + sollten so benannt werden, wie die Datenbankspalte ebenfalls hei=DF= t. + + 2.3 Variablennamen sollten in Englisch gehalten sein, weil der Rest + des Programms ebenfalls in Englisch gehalten ist. F=FCr Begriffe, + f=FCr die es keine englischen Entsprechungen gibt, sind deutsche + Variablennamen in Ordnung. + +3. Die Schreibweise von Variablen sollte komplett klein ein. Zusammenges= etzte + Namen sollten mit Unterstrichen getrennt werden. Beispiel: "$net_pric= e". + +4. Kommentare + + 4.1 Kommentare beziehen sich immer auf Code in der gleichen Zeile, wen= n + der Kommentar am rechten Rand steht, oder auf den nachfolgen Code. + + 4.2 Codeteile, deren Funktion nicht auf den ersten Blick ersichtlich i= st, + 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=E4nde= rt + hat, sind nicht notwendig. Daf=FCr gibt es die SVN-Commit-Nachrich= ten, + die all diese Informationen enthalten bzw. enthalten m=FCssen. + + 4.4 Funktionen sollten kommentiert werden. Dazu wird vor der Funktion + ein Kommentarblock erstellt, der beschreibt, was diese Funktion + tut. Zus=E4tzlich sollte aufgez=E4hlt werden, welche Parameter die + Funktion erwartet und welche Bedeutung diese haben. Der R=FCckgabe= wert + ist ebenfalls zu dokumentieren. + +5. Alle Texte/Begriffe, die ausgegeben werden, m=FCssen mit + $text->locale('Begriff'); ausgegeben werden, damit diese Begriffe + =FCbersetzt werden k=F6nnen. Das betrifft aber nur Begriffe, die einz= eln + =FCbersetzbar sind, nat=FCrlich nicht f=FCr z.B. HTML-Code. + +6. =C4nderungen in den Kernbestandteilen von Lx-Office, die nur der Anbi= ndung + von Modulen dienen, die wiederum nicht Bestandteil der offiziellen + Distribution sind, m=FCssen durch eine Konfigurationsvariable abschal= tbar + sein. Damit soll verhindert werden, dass solcher Code ausgef=FChrt wi= rd, + wenn das Modul nicht installiert ist, da dieser Code ausschlie=DFlich= von + den Programmierern dieses Moduls getestet werden kann. + + + + + +(B) "Optik" -- Sachen, die die Form betreffen +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + 1. Es werden keine "echten" TAB-Zeichen sondern Leerzeichen verwendet. Perltidy: -nt =20 @@ -116,7 +181,7 @@ 8. Mehrzeilige Befehle =20 8.1 Werden die Parameter eines Funktionsaufrufes auf mehrere Zeilen - aufgeteilt, so m[ssen diese bis zu der Spalte einger=FCckt werden, + aufgeteilt, so m=FCssen diese bis zu der Spalte einger=FCckt werde= n, in der die ersten Funktionsparameter in der ersten Zeile stehen. Perltidy: -lp -vt=3D1 -vtc=3D1 Beispiel: @@ -153,7 +218,7 @@ $form->{"row_$i"} =3D $form->{"row_$i"} - 5; $some_hash{42} =3D 54; =20 -11. Die Maximale Zeilenl=E4nge ist nicht bescr=E4nkt. Zeilenl=E4ngen <=3D= 79 +11. Die Maximale Zeilenl=E4nge ist nicht beschr=E4nkt. Zeilenl=E4ngen <=3D= 79 helfen, weil sie dann im Textmodus / per SSH deutlich besser lesbar sind. Oft genug ist es aber nicht m=F6glich oder nur unter gro=DFen Verrenkungen, diese Vorgabe einzuhalten. @@ -161,8 +226,12 @@ Zeilen sollten nicht l=E4nger als 79 Zeichen sein. Perltidy: -l=3D79 =20 -------------------------------------------------------------------------= -- =20 + + +(C) Liste der perltidy-Optionen +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D + Vollst=E4ndige Liste aller Optionen, die ich f=FCr perltidy benutze. Die= se k=F6nnen in ~/.perltidyrc geschrieben werden: =20 @@ -195,3 +264,7 @@ -lp -vt=3D1 -vtc=3D1 + + + + |