| |
| * Link führt ins Internet |
|
| |
Wie sollen sie eingesetzt werden?
|
|
Die offiziellen Konventionen sollten als Basis dienen, Sie funktionieren nur, wenn sie von jedem eingehalten werden. Es kann projektspezifische Erweiterungen geben.
Kommentarkonventionen
Mit Kommentaren wird Quelltext leichter lesbar und ist für die spätere Weiterbearbeitung wie auch bei der Fehlersuche leichter zu handhaben. Sie wissen bereits, dass Kommentare vom Interpreter ignoriert werden und damit auch für die Ausgabe keine Rolle spielen. Ob also 10 KByte oder 30 KByte ist einfach ausgedrückt nicht relevant! Nun einige Empfehlungen:
Jede Funktion sollte mit einer kurzen Zweckbeschreibung beginnen. Schreiben Sie immer, wozu eine Funktion eingesetzt wurde und nicht wie sie arbeitet. Nennen Sie alle globalen oder externen Variablen, Objekte oder andere Elemente, die Sie innerhalb der Funktion nutzen oder ändern. Beschreiben Sie die Struktur und der Wertebereich der Rückgabewerte bei Funktionen.
if (signal == TRUE) {
lampe = true; // Licht Ein
} else {
lampe = false; // Licht Aus
}
|
Sie können mit Hilfe der Kommentarzeichen // am Ende einer Befehlszeile einen Kommentar setzen. Nutzen Sie diese Technik, um wichtige Variablen am Ort Ihrer Deklaration zu beschreiben. Vermeiden Sie es jedoch, jede Hilfs- oder Zählvariable zu kommentieren, das führt zu unübersichtlichem Code. Denken Sie auch daran, dass Variablennamen selbsterklärend sein sollten und zusätzliche Informationen nicht zur Regel werden.
Block-Kommentare
Am Beginn des Skripts selbst sollte ebenfalls eine kurze Beschreibung der Funktionalität stehen. Auf komplexe Algorithmen kann hingewiesen werden. Es ist besonders bei grösseren Projekten sinnvoll, den Namen des Autors, das Datum der Freigabe, die Versionsnummer und die Versionsfolge zu beschreiben.
Es gibt einige allgemein übliche Schreibweisen zur Darstellung von wichtigen Kommentaren, die vor allem bei der Teamarbeit sehr nützlich sein können.
//:TODO:
Zeigt an, dass hier noch etwas getan werden muss.
//:BUG: [bugID]
Thema bzw. Problem. Der Kommentar sollte den Fehler beschreiben und eine Fehlernummer enthalten.
//:KLUDGE:
Zeigt an, dass der Code nicht optimal ist und symbolisiert damit einen Aufruf an die anderen Entwickler im Team, Verbesserungsvorschläge zu machen.
//:TRICKY:
Zeigt an, dass dieser Code recht komplex ist und daher bei der Bearbeitung vorab gut darüber nachgedacht werden sollte, welche Veränderungen vorgenommen werden.
Namenskonventionen
Die Gross- / Kleinschreibung ist für die Lesbarkeit enorm wichtig.
Beispiel
$SPIELFIGUR / $SpielFigur / $spielfigur
|
Alle Bezeichner fangen mit Kleinbuchstaben an. Bezeichner sind Namen für Variablen, Funktionen, Objekte.
Beispiel
$farbe / rennen() / $bild
|
Da in Bezeichnern keine Leerzeichen verwendet werden dürfen, sollte jedes neue Wort mit einem Grossbuchstaben anfangen.
Beispiel
setzeFarbe() / verwendeFarbe() / $initArray / $quizFrage
|
| Hinweis: Eine Ausnahme stellen bei der Bezeichnung die Objekte dar. Bei ihnen hat es sich durchgesetzt, sie mit einem Grossbuchstaben zu beginnen. |
Nachdem man sich in PHP eingearbeitet hat, sollte man auch in der Programmierung dazu übergehen, die Syntax in englisch zu halten. Da PHP auch in englisch gehalten ist, ergibt sich dadurch ein einheitliches Sprachbild, damit fällt auch die Verwendung von Abkürzungen um einiges leichter. Die Konvention kann jedoch nach eigenem Ermessen in die Arbeit einbezogen oder ignoriert werden. Eines sollten Sie jedoch immer beachten: Verwenden Sie nie Umlaute!
Beispiel
$Platzhalter (Besser: $dummy)
|
| Hinweis: In diesem Buch werden Sie in den meisten Beispielen vor allem deutschsprachig formulierte Beispiele vorfinden, so dass auch diejenigen unter Ihnen, die sich mit der englischen Sprache noch nicht anfreunden konnten, ohne weiteres die Zusammenhänge verstehen sollten. |
Abkürzungen sind erlaubt, wenn Sie konsequent und sinnvoll eingesetzt werden. Bis auf wenige Ausnahmen sind einbuchstabige Bezeichner zwar schneller in der Ausführung, jedoch stellen Sie einen schlechten Kompromiss zur Lesbarkeit dar.
Beispiel
$punktestand statt nur $ps für eine Punktestand
|
Konstanten können durch Grossbuchstaben hervorgehoben werden, da sich ihr Wert nicht ändert.
Beispiel
Bestehen die Namen aus mehreren Wörtern, werden die Wörter mit dem Unterstrich ( _ ) getrennt und alle Buchstaben gross geschrieben. Eine weitere Alternative wäre, ein Präfix oder Postfix zur Kennzeichnung zu verwenden.
Beispiel
// Konstante
ConMeineKonstante
MeineKonstanteCon
|
Hier eine Liste von Vorschlägen bezogen auf Variablen und Datentypen.
| Datentyp | Präfix | Beispiel |
| Array | arr | $arrPersonen, $personen_arr |
| Boolean | bln | $blnSignal, $signal_bln |
| Byte | byt | $bytWert, $wert_byt |
| Date | dt | $dtMorgen, $morgen_dt |
| Double | dbl | $dblPreis, $preis_dbl |
| Error | err | $errWert, $wert_err |
| Integer | int | $intPunkte, $punkte_int |
| Long | lng | $lngAbstand, $abstand_lng |
| Object | obj | $objHaus, $haus_obj |
| Single | sng | $sngWert, $wert_sng |
| String | str | $strName, $name_str |
Deklarationskonventionen
Es sollte möglichst nur eine Deklaration pro Zeile erfolgen.
var $name; // Vor- und Nachname
var $straße; // Straße mit Hausnummer
var $name, $straße; // Möglichst vermeiden
|
Es dürfen keine Deklarationen unterschiedlichen:
. Typs
. Methodendeklarationen
. Attributsdeklarationen
in einer Zeile stehen.
var $kundennummer, getKundennummer(); // Vermeiden
var $name, $namensliste[]; // Vermeiden
|
Deklarationen sollten immer am Anfang eines Blocks stehen.
Mit Variablendeklarationen sollte nicht bis zur ersten Verwendung gewartet werden. Lokale Variablen sollten bei Deklaration möglichst auch initialisiert werden.
Das Überdecken von Variablen in einer höheren Ebene sollten vermieden werden.
function meinFunktion () {
var $zaehler;
if (Bedingung) {
var $zaehler; // Vermeiden!
}
}
|
Anweisungskonventionen
Eine Zeile sollte nur einen Ausdruck enthalten.
$i++; $j++; // Vermeiden!
$zahlEins++; $zahlZwei--; // Vermeiden!
|
In Blöcken sollten öffnende Klammern am Zeilenende stehen.
if (Bedingung) {
Anweisungen;
}
if (Bedingung) {
Anweisungen;
} else {
Anweisungen;
}
|
Textformatierung und Strukturierung
Um Programmstrukturen lesen zu können, hat sich bei fast allen Programmiersprachen die Strukturierung des Codes durch Einrückungen etabliert. Dieses kann im PHP Editorfenster im Expertenmodus mit der -Taste manuell vorgenommen werden.
Der folgende Quellttext zeigt, wie eine gute Codestrukturierung aussehen könnte.
function setPosition($par) {
return $par;
}
|
|
|
|
|
|
|
|
SELFPHP
SELFPHP - Damir Enseleit, info@selfphp.de, Impressum, Kontakt