Entwicklerrichtlinien/Styleguide
|
Diese Seite sollte nochmals überarbeitet werden. Eine Begründung befindet sich in der Regel unter Diskussion (oben). |
Leben mit Debian: Die Entwickler Richtlinien
Alles was programmiert wird, soll sich an diese Richtlinien halten. Einige Dinge wie die Paketerstellung & -verwaltung, sowie die Konfiguration des Installers müssen sich auch an die "Debian Policy" halten.
Styleguide
Für das einheitliche Aussehen aller delixs-Werkzeuge, folgend "Admin-Interface" genannt, wird ein Styleguide erstellt.
Warum ein Styleguide?
Es handelt sich bei Quellcodes nach heute herrschender Meinung um technische Produkte und nicht um künstlerische Artefakte. Daher sind 'abgefahrene' und individuelle Formatierungen fehl am Platze. Es ist erwünscht, dass man bei den Quelltexten von mehreren Software-Entwicklern in einem Team nicht unterscheiden kann, wer welchen Code verfasst hat.
Es gibt eine weitere Argumentation, warum man soviel Wind um einen guten Stil macht. Das Boehm's Gesetz sagt, dass die Wartungskosten im Schnitt viermal größer sind als die Erstellungskosten. Das bedeutet, dass es sehr sinnvoll ist, den Code in Hinsicht Lesbarkeit zu optimieren.
Noch besser ist es, wenn in Hinsicht Verständlichkeit optimiert wird. Bitte immer vergegenwärtigen: einfach zu lesen und einfach zu verstehen ist nicht unbedingt das Gleiche.
Deshalb wurden für alle (Perl-)Scripte, die für dieses Projekt erstellt werden, die folgenden Festlegungen getroffen. Diese orientieren sich an der "Bibel für Perlprogrammierer", dem Buch "Perl Best Practices" von Damian Conway. Es wird aber nur ein ganz kleines Subset der Regeln dieses Buches hier herangezogen und auf Änderungen im Vergleich zu den dort angegebenen Regeln wird explizit hingewiesen. (Es ist damit kaum sinnvoll möglich, das bekannte Testmodul "Perl::Critic" einzusetzen.) In Hinblick auf die Kommentierung wird davon ausgegangen, dass eine typische Perldoc-Dokumentation erstellt wird, die aber debian-typisch als Man-Page bereitgestellt wird.
Codelayout
Klammerung
wir klammern generell im K&R-Stil:
my @names = ( 'schoffer', 'flesch', 'kirmse' )
oder
foreach my $zeile (@zeilen) {
if ($zeile ne ) {
print $zeile;
}
}
Schlüsselwörter
Schlüsselwörter bei Kontrollstrukturen sollen klar erkennbar sein und nicht fälschlich als Funktionsaufrufe interpretiert werden können. Zwischen Schlüsselwörtern und den Klammern schreiben sie unbedingt Leerzeichen wie in den zwei gerade angegebenen Beispielen.
Im Gegensatz dazu: bei Unterroutinen und Variablennamen schreiben Sie die Klammern direkt hinter diese Bezeichner.
my $password = &get_password($datei);
oder
my $element = $hash[2]{$nummer};
Operatoren
Nutzen Sie (ein) Leerzeichen, um binäre Operatoren von den Operanden abzuheben.
my $tage = time / 3600 / 24;
Einrückung
Verwenden Sie 2 Leerzeichen für eine Einrückungsebene Anm.: Conway - 4 Lerrzeichen
while ($zeile = <DATEI>) {
if ($zeile ne ) {
($erstes_element) = split ',', $zeile;
print $erstes_element, "\n";
}
}
Blöcke
Geben Sie niemals 2 Anweisungen in der gleichen Zeile ein
if ($a > $b) { # tauschen von $a und $b
$c = $b;
$b = $a;
$a = $c;
}
Else-Konstrukte
"Herzen" Sie das else nicht. Das bedeutet, das Folgendes NICHT in einer Zeile stehen soll:
} else {
sondern schreiben Sie es wie in dem folgenden Beispiel:
if ($a > $b) {
print "$a ist größer als $b \n";
}
else {
print "$a ist nicht größer als $b \n";
}
Namenskonventionen
Namen für Variablen
folgende Bildungsvorschrift liefert verständliche Bezeichner:
variable -> [adjektiv_]* substantiv
Beispiele: $naechster_client, $letzter_zeitpunkt, $aktueller_aufruf
Ein besonderer Fall sind Hashs und Arrays für Lookup-Tabellen. Hier ist folgende Bildungsvorschrift zu empfehlen:
lookup_variable -> [adjektiv_]* nomen präposition
Beispiele: %titel_von, %ISBN_fuer
Das liest sich dann im Quelltext so:
foreach my $buch (@katalog) {
print "Buch: $titel_von{$buch} - ISBN: $ISBN_fuer{$buch} \n";
}
Namen für Subroutinen und Methoden
Vorschlag für Bildungvorschrift
routine -> imperatives_verb [_adjektiv]? _nomen
Beispiele: &lies_datensatz, &generiere_profil, &schreibe_aktuellen_zaehler
Boolsche Variablen bzw. Routinen
Diese Variablen und Routinen sollten (als Sonderfall) nach ihren Test benannt werden.
Beispiele: &ist_gueltig, $hat_fehlerhaften_datensatz_gefunden
if (&ist_gueltig($naechster_datensatz)) {
# ...
}
else {
$hat_fehlerhaften_datensatz_gefunden = 1;
}
Referenzvariablen
Um sofort erkennen zu können, dass eine skalare Variable eine Referenz ist, sollte das Kürzel _ref angehangen werden.
$opts_ref, $user_ref ...
sub demo {
my $parameter_ref = shift;
my %parameter = %{$parameter_ref};
# ...
}
Hashs und Arrays
Benennen Sie (normalerweise) Hashs in der Einzahl und Arrays in der Mehrzahl. Bei Hash ist es häufig noch besser lesar, wenn dem singulären Nomen eine Präposition folgt.
Beispiele: %titel, %titel_von, %option, @ereignisse, @pcs ...
Unterstriche
Im Englischen werden Namen, die aus mehreren Wörtern bestehen, durch Bindestiche oder durch Leerzeichen "verbunden". z.B. "input stream", "double-click"
Da dies in Perl keine gültigen Bezeichner ergibt, ist nächstbeste Alternative der Unterstrich, wie sie in den vorangegangenen Beispielen verwendet wurden.
Die AlternativeMitEingestreutenGrossbuchstaben ist nicht so gut lesbar.
Gross- bzw. Kleinschreibung
Verwenden Sie
- verwenden Sie nur Kleinbuchstaben für Variablen, Subroutinen und Methoden.
- verwenden Sie die gemischte Gross- und Kleinschreibweise für Namen von Paketen und Klassen (z.B. Delixs::LDAP)
- Verwenden Sie Grossbuchstaben für Filehandle und Konstanten (z.B. DATEI, MAX_ANZAHL, LEERZEICHEN)
Utility-Routinen
Stellen Sie Routinen, die nur für den internen Gebrauch bestimmt sind, einen Unterstrich voran
Beispiel: &_finde_groesste_uid
Da diese Hilfsfunktion nicht exportiert wird (besser: werden sollte), fällt der Bezeichner mit den Unterstrich am Anfang im Hauptprogramm doch hoffentlich auf. ;)
Kontrollstrukturen
Verwenden sie bei Schleifen benannte Iteratoren, nicht $_
Qualitätssicherung
Wenn sie ihr Script bzw. ihre Lösung dem delixs-Projekt zur Verfügung stellen wollen, dann muss es wegen der langfristigen Sicherung des Supports bestimmten Ansprüchen genügen. Diese Qualitätsansprüche werden im Folgenden angegeben:
- Passworte, Hostnamen, IP-Adressen oder kurz: sämtliche variablen Daten sind nie im Script direkt anzugeben, sondern sollten immer aus der jeweiligen Datei (Beispiel: "ldap.secret") eingelesen werden.
- da jede Schule eine andere Suchbasis (hier LDAP-Base genannt) hat, sollte das Script diese aus der /etc/ldap.conf auslesen. Das kann so geschehen:
# wir holen uns die Such-Basis ($ldap_base) aus der ldap.conf
open DATEI, '<', '/etc/ldap.conf'
or die "konnte ldap.conf nicht oeffnen, $!\n";
while (my $zeile = <DATEI>) {
if ($zeile =~ m/^\s*base\s+(\w.*\w)\s*$/) {
$ldap_base = $1;
last;
}
}
close DATEI;