(:redirect 'http://docs.studip.de/develop/Entwickler/HowToFileTypes':)

Coding-Style

Alle Dateien müssen sich an die Coding-Standards halten.

Tipps

Grafiken werden in den Formaten JPG und PNG verwendet. Daumenregel: PNG für Bilder mit Transparenz und kleine Grafiken, die als PNG eine geringere Dateigröße haben. Für alles andere ist JPG angesagt.

• Variablen sollten aussagekräftige Namen haben. Zusammengesetzte Namen sind mit Unterstrich oder Großbuchstaben zu trennen. (Bei Variablen unterscheidet PHP zwischen Groß- und Kleinschreibung).
• Konstanten werden durchgängig groß und mit Unterstrichen zwischen den Wörtern geschrieben. (u.U. ist eine ‚echte’ Konstante (mit define) besser als eine Variable. Solche Konstanten können aber nur skalare Werte haben.)
• Globale Variablen sollten extra gekennzeichnet werden, z.B. mit einem Unterstrich beginnen.

• Die bevorzugte Sprache für Code und Kommentare ist Englisch.
• Kommentare sollen der PHPDoc Syntax folgen. ( SyntaxBeschreibung )
• Weitere Inline Kommentare sollten an komplexeren Stellen des Codes stehen Hilfestellungen zum Verstehen der Programmlogik sein.
• Kommentare sollen generell entweder C-Stil (/**/) oder C++/Java Standard (//) benutzen, nicht perl/shell Stil(#).

Externe Dateien einbinden

Funktionsaufrufe

Beispiel:

Funktionsdefinitionen

• Funktionen sollten aussagekräftige Namen haben.
• Für die Benennung von Klassen, Methoden und Funktionen gilt:
  • Klassennamen werden in MixedCaseSyntax geschrieben
  • Methodennamen in mixedCaseSyntax
  • Funktionen (die also nicht Teil von Klassendefinitionen sind) in underscore_syntax
  • Argumente mit Standardwerten kommen ans Ende der Liste. Eine Funktion sollte immer einen Rückgabewert haben (wenn sie überhaupt etwas zurückgeben kann), also z.B. false wenn kein sinnvoller Wert berechnet werden konnte.
  • Sehr lange Argumentslisten sind zu vermeiden, es ist besser dann ein Array zu übergeben. Häufig ist es auch sinnvoller die Funktion in mehrere kleinere zu zerlegen.

Beispiel:

(:source lang=php:)[@ function connect (&$dsn, $persistent = false) {

}@]

• Referenzen als Argumente sollten nur benutzt werden, wenn es sich nicht vermeiden lässt, d.h. wenn die Funktion auch wirklich den Inhalt der Variablen verändern muss. Die Performance von Übergaben als Referenz ist selten schneller, meist sogar langsamer, so dass sie sich nur bei großen Arrays oder Objekten lohnt.
• Klassen und Funktionen sollten, sofern sie mehr als einmal verwendet werden können, in separate Dateien ausgelagert werden.

• Kommentare sollen der PHPDoc Syntax folgen. ( SyntaxBeschreibung )
• Weitere Inline Kommentare sollten an komplexeren Stellen des Codes stehen Hilfestellungen zum Verstehen der Programmlogik sein.
• Kommentare sollen generell entweder C-Stil (/**/) oder C++/Java Standard (//) benutzen, nicht perl/shell Stil(#).

Kontrollstrukturen (if,else,switch,for …)

• Kontrollwörter sollten ein Leerzeichen zwischen sich und der öffnenden Klammer haben, um sie leichter von Funktionsaufrufen unterscheiden zu können.

Beispiel: (:source lang=php:)[@ if ((condition1) || (condition2)) {

}@]

• Geschweifte Klammern sollten auch bei einzelnen Anweisungen gesetzt werden, zumindest muss die Anweisung eingerückt in eine neue Zeile.

Operatoren

Operatoren sollten rechts und links von einem Leerzeichen umgeben sein.

$bar = 5;
$foo = $bar % 5;

Variablen

Allgemeines

• Die bevorzugte Sprache für Code und Kommentare ist Englisch.

Einrückung

• Einrückungen erfolgen nur mit Tabs.

Externe Dateien einbinden

• Externe Dateien werden mit include_once oder require_once eingebunden.

Funktionsaufrufe

Funktionsaufrufe sollten kein Leerzeichen zwischen Funktionsnamen und öffnender Klammer haben. Zwischen die einzelnen Parameter können zur besseren Lesbarkeit Leerzeichen eingefügt werden.

Beispiel:

$var = foo($bar, $baz, $quux);

Funktionsdefinitionen

- Funktionen sollten aussagekräftige Namen haben. - Für die Benennung von Klassen, Methoden und Funktionen gilt: – Klassennamen werden in MixedCaseSyntax geschrieben – Methodennamen in mixedCaseSyntax – Funktionen (die also nicht Teil von Klassendefinitionen sind) in underscore_syntax [comment=Tobias Thelen]Wobei zu beachten ist, dass PHP in Funktions- und Methodennamen intern nicht zwischen Groß und Kleinschreibung unterscheidet.[/comment][comment=Dipl.-Sozw. Cornelis Kater]Hier wäre es schön, sich generell festezulegen, wann ein Funktioname mit Unterstrich und durchweg kleingeschrieben, und wann ein Funktionsname ohne Unterstrich aber mit gemischter Groß-/Kleinschreibung geschrieben wird. Persönlich gefällt es mir besser generell auf Unterstriche zu verzichten (Tippt sich leicht ;-) [/comment][comment=Michael Riehemann]Ich stimme der Vorgabe zu![/comment][comment=Tobias Thelen]Gibt es in Java Funktionen? Ich dachte, das wären immer Methoden. Die obige Liste ist Ergebnis einer Diskussion hier im Developer-Board vor einiger Zeit.[/comment][comment=Marcus Lunzenauer]Da PHP ja nicht Java ist, kann man sich auch gerne von dortigen Konventionen lösen. Ich persönlich finde CamelCase für Methodennamen unübersichtlich und verwende durchweg Kleinbuchstaben durch Unterstriche getrennt.[/comment][comment=Torsten Heinrich]Ich finde die mixedCaseSyntax lesbarer und einfacher zu schreiben. Ist eine Unterscheidung bei der Schreibweise zwischen Funktionen und Methoden übherhaupt wichtig? Das ergibt sich doch aus dem Kontext,oder?[/comment] - Argumente mit Standardwerten kommen ans Ende der Liste. Eine Funktion sollte immer einen Rückgabewert haben (wenn sie überhaupt etwas zurückgeben kann), also z.B. wenn kein sinnvoller Wert berechnet werden konnte.[comment=Marcus Lunzenauer]Ein anderes Verhalten ist ja auch absolut unsinnvoll.. Das bräuchte hier nicht stehen.[/comment] - Sehr lange Argumentslisten sind zu vermeiden, es ist besser dann ein Array zu übergeben. Häufig ist es auch sinnvoller die Funktion in mehrere kleinere zu zerlegen.

Beispiel:

[code]function connect (&$dsn, $persistent = false) {

    if (is_array($dsn)) {
        $dsninfo = &$dsn;
    } else {
        $dsninfo = DB::parseDSN($dsn);
    }

    if (!$dsninfo || !$dsninfo['phptype']) {
        return $this->raiseError();
    }

    return true;

}[/code]

- Referenzen als Argumente sollten nur benutzt werden, wenn es sich nicht vermeiden lässt, d.h. wenn die Funktion auch wirklich den Inhalt der Variablen verändern muss. Die Performance von Übergaben als Referenz ist selten schneller, meist sogar langsamer, so dass sie sich nur bei großen Arrays oder Objekten lohnt.[comment=Marcus Lunzenauer]Dass die Performance leidet kann ich ganz und gar nicht bestätigen. In meinen Tests ist das genau umgekehrt. Generell ist das ja aber eher ein Problem von PHP4 und Objekten. Mit PHP5 würde dieser Absatz eh entfallen.[/comment]

- Klassen und Funktionen sollten, sofern sie mehr als einmal verwendet werden können, in separate Dateien ausgelagert werden.

Kommentare

- Kommentare sollen der PHPDoc Syntax folgen. ( SyntaxBeschreibung ) - Weitere Inline Kommentare sollten an komplexeren Stellen des Codes stehen Hilfestellungen zum Verstehen der Programmlogik sein. - Kommentare sollen generell entweder C-Stil (/**/) oder C++/Java Standard (//) benutzen, nicht perl/shell Stil(#).[comment=Michael Riehemann]Kommentare englisch oder deutsch?[/comment][comment=Marcus Lunzenauer]Und welchen Grund gibt es, #-Kommentare nicht zu erlauben?[/comment][comment=Elmar Ludwig]Weil eine einzeilige Kommentarsyntax völlig reicht?[/comment][comment=Christian Hueser]Häufig wird /* */ und // für Kommentare und # zum Auskommentieren von Code benutzt. PEAR Coding Standard empfiehlt jedoch das auch hier vorgeschlagene.[/comment]

Kontroll Strukturen (if,else,switch,for …)

- Kontrollwörter sollten ein Leerzeichen zwischen sich und der öffnenden Klammer haben, um sie leichter von Funktionsaufrufen unterscheiden zu können.

Beispiel:

[code]if ((condition1) || (condition2)) {

    action1;

} elseif ((condition3) && (condition4)) {

    action2;

} else {

    defaultaction;

}[/code]

- Geschweifte Klammern sollten auch bei einzelnen Anweisungen gesetzt werden, zumindest muss die Anweisung eingerückt in eine neue Zeile.[comment=Michael Riehemann]Klammern sollten IMMER gesetzt werden und auch innere Bereiche IMMER einrücken.[/comment]

Operatoren

Operatoren sollten rechts und links von einem Leerzeichen umgeben sein.[comment=Cornelius Hempel]Ist das wirklich immer sinnvoll? Sollte man das vielleicht auf bestimmte Operatoren einschränken oder wenigstens konkretisieren?[/comment][comment=Elmar Ludwig]Bei welchen Operatoren würdest Du denn darauf verzichten wollen?[/comment]

Beispiel:

[code]$bar = 5; $foo = $bar % 5;[/code]

Variablen

- Variablen sollten aussagekräftige Namen haben. Zusammengesetzte Namen sind mit Unterstrich oder Großbuchstaben zu trennen. (Bei Variablen unterscheidet PHP zwischen Groß- und Kleinschreibung). - Konstanten werden durchgängig groß und mit Unterstrichen zwischen den Wörtern geschrieben. (u.U. ist eine ‚echte’ Konstante (mit define) besser als eine Variable. Solche Konstanten können aber nur skalare Werte haben.)[comment=Elmar Ludwig]Meines Erachtens sollte man skalare Konstante immer mit define definieren.[/comment] - Globale Variablen sollten extra gekennzeichnet werden, z.B. mit einem Unterstrich beginnen. [comment=Marcus Lunzenauer]Oha, ist das ernst gemeint?[/comment][comment=Elmar Ludwig]Sorry, aber der Unterstrich wird seit ewigen Zeiten und in praktisch allen Programmiersprachen für interne Symbole verwendet, die nicht Teil der öffentlichen API sind. Wenn schon kennzeichnen (was ich nicht für notwendig halte), dann bitte anders…[/comment]

• Session Variablen, die nur von einem bestimmten Script genutzt werden, sollten den Namen des Scriptes mit dem Zusatz "_data" enthalten, etwa bekommt die edit_about die Sessionvariable edit_about_data zugeteilt. So verhindert man Probleme mit gleichen Sessionvariablen auf verschiedenen Seiten.

generierter HTML-Code

• aus Gründen der Übersichtlichkeit (Debugging!) müssen bei aus PHP heraus generiertem html ausreichend und sinnvoll plazierte Zeilenende ("\n") eingefügt werden.
• eine Einrückung des html-Codes kann durch vorangestellte "\t" erzeugt werden.

Grafiken werden in den Formaten JPG und GIF verwendet. Daumenregel: GIF für animierte Bilder, Bilder mit Transparenz und kleine Grafiken, die als GIF eine geringere Dateigröße haben. Für alles andere ist JPG angesagt.

Die allermeisten Stud.IP-Quelldateien sind PHP-Dateien, die z.T. HTML-Teile enthalten. Mittelfristig werden PHP-Code und HTML-Ausgaben strikter getrennt - s. HTML-Ausgaben erzeugen.

Coding-Style

Kommentar-Konventionen

Tipps

Grafiken werden in den Formaten JPG und GIF verwendet. Daumenregel: GIF für animierte Bilder, Bilder mit Transparenz und kleine Grafiken, die als GIF eine geringere Dateigröße haben. Für alles andere wird JPG verwendet.

< Orientierung im Verzeichnisbaum | Entwicklungs-HOWTO | API-Dokumentation >

Entwicklungs-HOWTO: Dateitypen und Coding-Style

(:toc:)

PHP-Dateien

Die allermeisten Stud.IP-Quelldateien sind PHP-Dateien.

TODO

Grafiken

TODO

Sonstige

TODO