phpBB

Development Wiki

Deutsch:Coding guidelines

From phpBB Development Wiki

Revision as of 10:59, 26 August 2007 by GqqFf0 (Talk | contribs)

Dies ist der Beginn der Übersetzung der Coding Guidelines der Version 1.22

Coding Guidelines

Vorgaben/Voreinstellungen

Editor-Einstellungen

Tabs vs. Leerzeichen Um das Lesen so einfach wie möglich zu machen, werden wir Tabs und keine Leerzeichen verwenden. Wir verwenden 4 (vier) Leerzeichen für ein Tab - deshalb müssen Sie Ihre Tab-Breite im Editor auf 4 Leerzeichen setzen. Stellen Sie sicher, dass, wenn Sie die Datei speichern, er Tabs und keine Leerzeichen speichert. Auf diese Weise kann der Code in der Art angezeigt werden wie wir es wollen, ohne das Layout der wirklichen Dateien zu stören.

Tabs vor in den Zeilen vor dem Code sind kein Problem, aber innerhalb eines Textes kann es zu einem Problem kommen, wenn ihre Einstellungen sich von unseren unterscheiden. Hier ein kurzes Beispiel wie es aussehen sollte:

{TAB}$mode{TAB}{TAB}= request_var('mode''');
{
TAB}$search_id{TAB}= request_var('search_id''');

Wenn mit Tabs eingegeben wird (ersetzen sie {TAB}), müssen beide gleichen Zeichen auf derselben Höhe sein.

Zeilenumbrüche:

Stellen Sie Sicher, dass Ihr Editor Dateien im UNIX-Format speichert. Das bedeutet, dass Zeilen mit einem newline gespeichert werden, nicht mit einer CR/LF Combo, wie unter Win32, oder dem, was auch immer ein Mac benutzt. Jeder anständige Editor sollte diese Einstellung bieten, aber es könnte nicht die Standard-Einstellung sein. Lernen Sie mit ihrem Editor umzugehen. Wenn Sie Rat über Windows-Editor wollen, können Sie einen der Entwickler fragen. Einige von ihnen arbeiten ebenfalls mit Win32.

File Header/Kopfzeilen

Standard Header für neue Dateien:

Diese Vorgabe für den Kopf muss an den Anfang aller phpBB Dateien eingefügt werden:

/**
*
* @package {Paketname}
* @version $Id: $
* @copyright (c) 2006 phpBB Group 
* @license http://opensource.org/licenses/gpl-license.php GNU Public License 
*
*/

Bitte schauen sie in den Abschnitt 'Datei Positionen' um den richtigen Paketnamen zu erfahren.

Dateien, die Code beinhalten:

Für diese Dateien müssen sie einen leeren Kommentar direkt nach dem Kopf/Header einfügen, um zu verhindern, dass automatische Dokumentationsprogramme den Kopfteil als Erläuterung für die ersten Code-Zeilen interpretieren.

/**
* {Kopfteil/Header}
*/

/**
*/
{CODE}

Dateien die nur Funktionen beinhalten:

Vergessen Sie nicht die Funktion zu kommentieren (insbesondere die erste Funktion die auf den Kopf/Header folgt). Jede Funktion sollte zumindest einen Kommentar haben, der erklärt was die Funktion macht. Für komplexere Funktionen wird empfohlen die Parameter ebenfalls zu kommentieren.

Dateien die nur Klassen enthalten:

Vergessen Sie nicht die Klasse zu kommentieren. Klassen benötigen eine separate @package-Definition, es ist die gleiche wie die im Kopfteil/Header. Abgesehen von diesem Sonderfall, gilt das gleiche für die Klassen, sowie deren Methoden wie für Dateien die nur Funktionen beinhalten.

Code der auf den Kopfteil/Header folgt in Dateien die nur Funktionen/Klassen enthalten:

Wenn dieser Fall zutrifft, ist die beste Methode die die Dokumentation vereinfacht, einen Kommentar mit einer ignore Anweisung zu verwenden, als Beispiel:

/**
* {Kopfteil/Header}
*/

/**
* @ignore
*/
Kleiner Codeabschnittmeistens nur ein oder zwei Definitionen oder eine if-Abfrage

/**
* {Dokumentation}
*/
class ...

Datei Positionen

Funktionen die von mehr als einer Seite benutzt wird, gehören in die Datei functions.php, Funktionen die speziell für eine Datei sind sollten in dieser Datei (am Ende) oder in die für den Bereich entsprechende Funktionsdatei. Manche Dateien in dem /includes Ordner sind für spezielle Bereiche zuständig. Zum Beispiel Datei-Uploads, das Anzeigen von etwas, Benutzerspezifische Funktionen und so weiter.

Die folgenden Pakete sind vordefiniert, und dazu passende Features/Funktionen sollten in den erwähnten Dateien/Positionen platziert werden, genauso wie der spezifische Paketname benutzt werden sollte. Die Paketnamen sind fett in der folgenden Liste:


  • phpBB3
Core/Basis Dateien und alle Dateien die nicht in ein separates Paket gehören
  • acm
/includes/acm, /includes/cache.php
Dateien für das Caching
  • acp
/adm, /includes/acp, /includes/functions_admin.php
Administrationsbereich
  • dbal
/includes/db
Abstrakte Datenbankschicht / Database Abstraction Layer.
Basis Klasse ist dbal
  • /includes/db/dbal.php
Basis Datenbank Abstraktions Klasse, definiert die Schnittstelle zur Datenbanken und für alle Datenbanktypen gültiges
  • /includes/db/firebird.php
Firebird/Interbase Datenbank Abstraktion
  • /includes/db/msssql.php
MSSQL Datenbank Abstraktion
  • /includes/db/mssql_odbc.php
MSSQL ODBC Datenbank Abstraktion für MSSQL
  • /includes/db/mysql.php
MySQL Datenbank Abstraktion für MySQL 3.x/4.0.x
  • /includes/db/mysql4.php

::MySQL4 Datenbank Abstraktion für MySQL 4.1.x/5.x

  • /includes/db/mysqli.php
MySQLi Datenbank Abstraktion
  • /includes/db/oracle.php
Oracle Datenbank Abstraktion
  • /includes/db/postgres.php
PostgreSQL Datenbank Abstraktion
  • /includes/db/sqlite.php
Sqlite Datenbank Abstraktion
  • docs
/docs
phpBB Dokumentation
  • images
/images
Alle allgemeinen Bilder, die nicht zu einem Style gehören
  • install
/install
Installationssystem
  • language
/language
Alle Sprachdateien
  • login
/includes/auth
Plugins für den Login und die Authentifizierung
  • VC
/includes/captcha
CAPTCHA
  • mcp
mcp.php, /includes/mcp, report.php
Moderationsbereich
  • ucp
ucp.php, /includes/ucp
Benutzerbereich
  • search
/includes/search, search.php
Suchsystem
  • styles
/styles, style.php
phpBB Styles/Templates/Themes/Imagesets

Code Layout/Guidelines

Bitte denken sie daran, das diese Richtlinien auf alle php, html, javascript und css Dateien angewendet werden sollen

Variablen-/Funktions-Namensgebung

Wir werden keine Form der ungarischen Notation verwenden. Viele von uns glauben das diese Notation eine der verworrensten Techniken die benutzt wird ist.

Variablen Namen:

Variablennamen sollten komplett kleingeschrieben werden, die Wörter durch den Unterstrich getrennt, Beispiel:

$current_user ist richtig, aber $currentuser und $currentUser sind es nicht

Namen sollten beschreibend, aber knapp sein. Wir wollen keine langen Sätze als Variablennamen, aber ein paar Buchstaben extra sind immer besser als sich zu fragen wofür die Variable denn nun verwendet wird.

Schleifen-Zähl-Variablen:

Die einzige Situation wo Variablen aus einem Buchstaben bestehen dürfen sind die Schleifen-Variablen. In diesem Fall sollte die Variable der äußerten Schleife immer $i sein. Wenn Schleifen innerhalb der Schleife sind, sollten deren Variablen $j, gefolgt von $k und so weiter sein. Wenn die Schleifenvariablen schon aussagekräftig sind, sollte diese Regel nicht angewendet werden, Beispiel:

for ($i 0$i $outer_size$i  )
{
   for (
$j 0$j $inner_size$j  )
   {
      
foo($i$j);
   }
}

Funktionsnamen:

Funktionsnamen sollten beschreibend sein. Wir programmieren ja kein C hier, wir wollen keine Funktionen schreiben die "stristr()" heißen. Wieder gilt: Kleinschreibung und Unterstriche als Trennung zwischen den Worten. Funktionen sollten ein Verb im Namen haben. Gute Funktionsnamen sind zum Beispiel print_login_status(), get_user_data(), usw.

Funktionsparameter:

Parameter sind Bestandteil derselben Richtlinien wie Variablennamen. Wir wollten keine Parameter wie do_stuff($a, $b, $c). In den meisten Fällen wollen wir in der Lage sein, zu wissen wie eine Funktion benutzt wird, indem wir auf die Funktionsdeklaration schauen.

Zusammenfassung:

Die grundlegende Philosophie hier ist die Lesbarkeit des Codes nicht zugunsten der Faulheit zu beeinträchtigen. Dies muss mit dem gesunden Menschenverstand gemacht werden, aber; print_login_status_for_a_given_user() ist zu lang, als Beispiel -- diese Funktion sollte besser print_user_login_status()', oder einfach print_login_status() heißen.

Spezielle Namen:

Für alle Emotions/Smilies gilt der Ausdruck smiley im Singular und smilies im Plural.

Code Layout

Immer geschweifte Klammern benutzen:

Dies ist ein anderes Beispiel für die Faulheit zwei extra Zeichen einzugeben, die die Code Lesbarkeit nicht vereinfachen. Selbst in dem Teil von manchen Abschnitten in den nur eine Zeile lang ist, vergesst die geschweiften Klammern nicht. Denkt einfach dran, Beispiel

// These are all wrong.

if (Bedingungdo_stuff();

if (
Bedingung)
    
do_stuff();

while (
Bedingung)
    
do_stuff();

for (
$i 0$i size$i  )
    
do_stuff($i);

// These are all right.

if (Bedingung)
{
    
do_stuff();
}

while (
Bedingung
{
    
do_stuff();
}

for (
$i 0$i size$i  
{
    
do_stuff();
}

Wo die geschweiften Klammern hingehören:

Um diese Frage wird häufig gestritten, wir haben es einfach gehalten: Geschweifte Klammern in ihre eigene Zeile, die schließende Klammer dazu sollte immer genau so weit eingerückt sein, Beispiel:

if (Bedingung
{
    while (
Bedingung2)
    {
        ...
    }
}
else 
{
    ...
}

for (
$i 0$i $size$i  
{
    ...
}
        
while (
Bedingung
{
    ...
}
        
function 
do_stuff() 
{
    ...
}

Benutzen Sie Leerzeichen zwischen den Ausdrücken/Tokens:

Dies ist ein weiterer, einfacher Schritt um Code ohne große Mühe lesbarer zu halten. Wann auch immer Sie eine Zuweisung, einen Ausdruck, oder ähnliches benutzen... Lassen sie immer ein Leerzeichen zwischen den Tokens. Schreiben Sie den Code immer so als wäre es die Englische(Deutsche) Sprache. Setzen sie Leerzeichen zwischen Namen und Operanden. Benutzen Sie keine Leerzeichen nach öffnenden oder vor schließenden Klammern. Setzen sie keine Leerzeichen vor ein Komma oder Semikolon. Dies kann man am besten an ein paar Beispielen zeigen.

// Jedes Paar zeigt erst die falsche, dann die richtige Schreibweise.''

$i=0;
$i 0;
        
if(
$i<7) ...
if (
$i 7) ...
        
if ( (
$i 7)