Code Styleguide: Unterschied zwischen den Versionen

Aus Contao Community Documentation

K (Header)
(Dateinamen: Klassennamen in UpperCamelCase, Objekte dann ggf. in LowerCamelCase)
 
(4 dazwischenliegende Versionen von 3 Benutzern werden nicht angezeigt)
Zeile 1: Zeile 1:
 
{{stub}}
 
{{stub}}
 +
[[en:Code_Styleguide]]
  
 
Diese Seite soll einen allgemeinen Styleguide für Entwicklung von Contao Extensions darstellen.
 
Diese Seite soll einen allgemeinen Styleguide für Entwicklung von Contao Extensions darstellen.
Zeile 10: Zeile 11:
 
Der Dateiname muss, damit die Klasse automatisch geladen werden kann (siehe [[Autoloader]]), gleich wie der Klassenname sein. Gross- und Kleinschreibung muss beachtet werden, da ansonsten auf Unix-/Linux-Servern die Klasse nicht gefunden werden kann.
 
Der Dateiname muss, damit die Klasse automatisch geladen werden kann (siehe [[Autoloader]]), gleich wie der Klassenname sein. Gross- und Kleinschreibung muss beachtet werden, da ansonsten auf Unix-/Linux-Servern die Klasse nicht gefunden werden kann.
  
Der Klassenname sollte, sofern er aus mehreren Worten besteht, in lower [[w:de:CamelCase|CamelCase]] geschrieben werden.
+
Der Klassenname sollte, sofern er aus mehreren Worten besteht, in [[w:de:CamelCase|UpperCamelCase]] geschrieben werden.
  
 
===Header===
 
===Header===
Zeile 21: Zeile 22:
 
Diese Informationen sollten bestenfalls in [[w:de:PhpDocumentor|PhpDocumentor Notation]] vorgenommen werden.
 
Diese Informationen sollten bestenfalls in [[w:de:PhpDocumentor|PhpDocumentor Notation]] vorgenommen werden.
 
Beispiel:
 
Beispiel:
/**
+
 
  * Contao Open Source CMS
+
<source lang="php">
  * Copyright (C) 2005-2010 Leo Feyer
+
/**
  *
+
* Contao Open Source CMS
  * Formerly known as TYPOlight Open Source CMS.
+
* Copyright (C) 2005-2010 Leo Feyer
  *
+
*
  * This program is free software: you can redistribute it and/or
+
* Formerly known as TYPOlight Open Source CMS.
  * modify it under the terms of the GNU Lesser General Public
+
*
  * License as published by the Free Software Foundation, either
+
* This program is free software: you can redistribute it and/or
  * version 3 of the License, or (at your option) any later version.
+
* modify it under the terms of the GNU Lesser General Public
  *
+
* License as published by the Free Software Foundation, either
  * This program is distributed in the hope that it will be useful,
+
* version 3 of the License, or (at your option) any later version.
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
+
*
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+
* This program is distributed in the hope that it will be useful,
  * Lesser General Public License for more details.
+
* but WITHOUT ANY WARRANTY; without even the implied warranty of
  *
+
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  * You should have received a copy of the GNU Lesser General Public
+
* Lesser General Public License for more details.
  * License along with this program. If not, please visit the Free
+
*
  * Software Foundation website at <http://www.gnu.org/licenses/>.
+
* You should have received a copy of the GNU Lesser General Public
  *
+
* License along with this program. If not, please visit the Free
  * PHP version 5
+
* Software Foundation website at <http://www.gnu.org/licenses/>.
  * @copyright  Some Company 2010
+
*
  * @author    Max Mustercoder <mustercoder@somedomain.tld>
+
* PHP version 5
  * @package    RealCoolExtension
+
* @copyright  Some Company 2010
  * @license    http://opensource.org/licenses/lgpl-3.0.html
+
* @author    Max Mustercoder <mustercoder@somedomain.tld>
  */
+
* @package    RealCoolExtension
 +
* @license    http://opensource.org/licenses/lgpl-3.0.html
 +
*/
 +
</source>
  
 
==Code==
 
==Code==
Zeile 54: Zeile 58:
  
 
===Klammerung, Leerzeichen und Kommata===
 
===Klammerung, Leerzeichen und Kommata===
In Contao werden geschweifte Klammern grundsätzlich auf eine neue Zeile geschoben. Nach öffnenden und schließenden runden Klammern wird kein Leerzeichen geschrieben. Nach einem Komma und Schleifen-Schlüsselwörtern (if, while, for, foreach) wird ein Leerzeichen eingefügt.
+
In Contao werden geschweifte Klammern grundsätzlich auf eine neue Zeile geschoben. Nach öffnenden und vor schließenden runden Klammern wird kein Leerzeichen geschrieben. Nach einem Komma und Schleifen-Schlüsselwörtern (if, while, for, foreach) wird ein Leerzeichen eingefügt.
  
 
Beispiel:
 
Beispiel:
public function somefunction($param)
+
 
{
+
<source lang="php">
if ($param=='foo')
+
public function somefunction($param)
{
+
{
// do something
+
  if ($param=='foo')
}
+
  {
else
+
    // do something
{
+
  }
// do something else
+
  else
}
+
  {
}
+
    // do something else
 +
  }
 +
}
 +
</source>
  
 
===Leerzeilen===
 
===Leerzeilen===
 
Leerzeilen sollten verwendet werden um logische Codeabschnitte zu gruppieren. Leerzeilen sollten von allen Tabulator- und Leerzeichen bereinigt werden und wirkliche Leerzeilen sein.
 
Leerzeilen sollten verwendet werden um logische Codeabschnitte zu gruppieren. Leerzeilen sollten von allen Tabulator- und Leerzeichen bereinigt werden und wirkliche Leerzeilen sein.
  
Nach einer Funktion (bzw. Methode) sollte mindestens eine Leerzeile folgen.
+
Nach einer Funktion (bzw. Methode) sollten zwei Leerzeilen folgen, nach einer Objekt-Variable jeweils eine Leerzeile.
  
 
===Zeilenlänge===
 
===Zeilenlänge===
 
Abweichend vom Contao Core sollte Code in Erweiterungen so geschrieben werden, dass er möglichst auf einen Blick sichtbar und damit wartbar ist, insbesondere sollte es nur in Ausnahmefällen nötig sein, horizontal zu rollen. Eine feste Maximal-Breite kann nicht sinnvoll definiert werden, weil das von zu vielen Dingen abhängt (verfügbare Pixel des Bildschirms, Größe der Schrift, Komplexität und Einrücktiefe des Codes). Dennoch kann man sich an der Lesbarkeit/Erfassbarkeit für Menschen orientieren (60-80 Zeichen/Zeile). Das ist verflixt wenig ... und kann nicht immer eingehalten werden. Jedoch erlauben sowohl PHP wie auch SQL Zeilen-Umbrüche, so dass man z.B. ein komplexes IF Statement auf mehrere kurze Zeilen verteilen kann (Beispiel folgt). Bei SQL Statements (im Core durchgängig auf einer Zeile mit teilweise mehreren hundert Zeichen) kann man den Query-String ohne weiteres auf mehrere Zeilen verteilen und damit erheblich leichter verständlich machen ... die Klasse "Database" bzw. die DB räumt überflüssige Leerzeichen automatisch auf. Beispiel:
 
Abweichend vom Contao Core sollte Code in Erweiterungen so geschrieben werden, dass er möglichst auf einen Blick sichtbar und damit wartbar ist, insbesondere sollte es nur in Ausnahmefällen nötig sein, horizontal zu rollen. Eine feste Maximal-Breite kann nicht sinnvoll definiert werden, weil das von zu vielen Dingen abhängt (verfügbare Pixel des Bildschirms, Größe der Schrift, Komplexität und Einrücktiefe des Codes). Dennoch kann man sich an der Lesbarkeit/Erfassbarkeit für Menschen orientieren (60-80 Zeichen/Zeile). Das ist verflixt wenig ... und kann nicht immer eingehalten werden. Jedoch erlauben sowohl PHP wie auch SQL Zeilen-Umbrüche, so dass man z.B. ein komplexes IF Statement auf mehrere kurze Zeilen verteilen kann (Beispiel folgt). Bei SQL Statements (im Core durchgängig auf einer Zeile mit teilweise mehreren hundert Zeichen) kann man den Query-String ohne weiteres auf mehrere Zeilen verteilen und damit erheblich leichter verständlich machen ... die Klasse "Database" bzw. die DB räumt überflüssige Leerzeichen automatisch auf. Beispiel:
  
SELECT  exp.*,
+
<source lang="sql">
          cty.city AS city_name
+
SELECT  exp.*,
FROM    tl_immo_expose AS exp,
+
        cty.city AS city_name
          tl_immo_city AS cty
+
FROM    tl_immo_expose AS exp,
WHERE    exp.city = cty.id
+
        tl_immo_city AS cty
AND      object_category = ?
+
WHERE    exp.city = cty.id
AND      object_status = ?
+
AND      object_category = ?
AND      object_type LIKE ?
+
AND      object_status = ?
AND      cty.city LIKE ?
+
AND      object_type LIKE ?
ORDER BY rooms ASC,
+
AND      cty.city LIKE ?
          stories ASC
+
ORDER BY rooms ASC,
 +
        stories ASC
 +
</source>
  
 
ist lesbar und halbwegs nachvollziehbar, jedoch das gleiche Statement auf einer einzigen Zeile (mit mehr als 220 Zeichen) ist nicht mehr wartbar:
 
ist lesbar und halbwegs nachvollziehbar, jedoch das gleiche Statement auf einer einzigen Zeile (mit mehr als 220 Zeichen) ist nicht mehr wartbar:
  
SELECT exp.*,cty.city AS city_name FROM tl_immo_expose AS exp,tl_immo_city AS cty WHERE exp.city = cty.id AND object_category = ? AND object_status = ? AND object_type LIKE ? AND cty.city LIKE ? ORDER BY rooms ASC,stories ASC
+
<source lang="sql">
 +
SELECT exp.*,cty.city AS city_name FROM tl_immo_expose AS exp,tl_immo_city AS cty WHERE exp.city = cty.id AND object_category = ? AND object_status = ? AND object_type LIKE ? AND cty.city LIKE ? ORDER BY rooms ASC,stories ASC
 +
</source>

Aktuelle Version vom 26. Mai 2013, 11:23 Uhr

MsgError.png Unvollständiger Artikel: dieser Artikel ist noch nicht sauber bearbeitet.

Bitte erweitere ihn und entferne erst anschliessend diesen Hinweis.

Diese Seite soll einen allgemeinen Styleguide für Entwicklung von Contao Extensions darstellen. Die hier gemachten Angaben entstanden aus der Auswertung des Contao Core, erheben jedoch keinen Anspruch auf Vollständigkeit, Richtigkeit oder gar Übereinstimmung mit den Ansichten des Core Entwicklers Leo Feyer.

Dateien

Dateinamen

In jeder Datei sollte nur eine Klasse enthalten sein. Ausgenommen sind Hilfsklassen, die nur von der einen Klasse aufgerufen werden, oder deren Aufruf die Einbindung der einen Klasse voraussetzt (siehe Database, Database_Statement, Database_Result).

Der Dateiname muss, damit die Klasse automatisch geladen werden kann (siehe Autoloader), gleich wie der Klassenname sein. Gross- und Kleinschreibung muss beachtet werden, da ansonsten auf Unix-/Linux-Servern die Klasse nicht gefunden werden kann.

Der Klassenname sollte, sofern er aus mehreren Worten besteht, in UpperCamelCase geschrieben werden.

Header

In jeder Datei sollte oben ein Header enthalten sein, welcher mindestens folgende Informationen beinhalten sollte:

  • die Lizenz, unter deren der Code veröffentlicht wurde.
  • der Name des Autors.
  • ggf. der Name der Firma, für welche der Code geschrieben wurde und deren geistiges Eigentum er somit ist.
  • das Paket, zu welchem die Datei gehört.

Diese Informationen sollten bestenfalls in PhpDocumentor Notation vorgenommen werden. Beispiel:

/**
 * Contao Open Source CMS
 * Copyright (C) 2005-2010 Leo Feyer
 *
 * Formerly known as TYPOlight Open Source CMS.
 *
 * This program is free software: you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation, either
 * version 3 of the License, or (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this program. If not, please visit the Free
 * Software Foundation website at <http://www.gnu.org/licenses/>.
 *
 * PHP version 5
 * @copyright  Some Company 2010
 * @author     Max Mustercoder <mustercoder@somedomain.tld>
 * @package    RealCoolExtension
 * @license    http://opensource.org/licenses/lgpl-3.0.html
 */

Code

Einrückung

In Contao werden zum Einrücken von Code in der Regel normale TABulatoren (ASCII 0x09) und keine Leerzeichen verwendet. Eine Ausnahme hiervon stellen Einrückungen von zwei bis drei Leerzeichen dar, welche zur Formatierung von beispielsweise Datenbankabfragen eingefügt werden können.

Klammerung, Leerzeichen und Kommata

In Contao werden geschweifte Klammern grundsätzlich auf eine neue Zeile geschoben. Nach öffnenden und vor schließenden runden Klammern wird kein Leerzeichen geschrieben. Nach einem Komma und Schleifen-Schlüsselwörtern (if, while, for, foreach) wird ein Leerzeichen eingefügt.

Beispiel:

public function somefunction($param)
{
   if ($param=='foo')
   {
     // do something
   }
   else
   {
     // do something else
   }
}

Leerzeilen

Leerzeilen sollten verwendet werden um logische Codeabschnitte zu gruppieren. Leerzeilen sollten von allen Tabulator- und Leerzeichen bereinigt werden und wirkliche Leerzeilen sein.

Nach einer Funktion (bzw. Methode) sollten zwei Leerzeilen folgen, nach einer Objekt-Variable jeweils eine Leerzeile.

Zeilenlänge

Abweichend vom Contao Core sollte Code in Erweiterungen so geschrieben werden, dass er möglichst auf einen Blick sichtbar und damit wartbar ist, insbesondere sollte es nur in Ausnahmefällen nötig sein, horizontal zu rollen. Eine feste Maximal-Breite kann nicht sinnvoll definiert werden, weil das von zu vielen Dingen abhängt (verfügbare Pixel des Bildschirms, Größe der Schrift, Komplexität und Einrücktiefe des Codes). Dennoch kann man sich an der Lesbarkeit/Erfassbarkeit für Menschen orientieren (60-80 Zeichen/Zeile). Das ist verflixt wenig ... und kann nicht immer eingehalten werden. Jedoch erlauben sowohl PHP wie auch SQL Zeilen-Umbrüche, so dass man z.B. ein komplexes IF Statement auf mehrere kurze Zeilen verteilen kann (Beispiel folgt). Bei SQL Statements (im Core durchgängig auf einer Zeile mit teilweise mehreren hundert Zeichen) kann man den Query-String ohne weiteres auf mehrere Zeilen verteilen und damit erheblich leichter verständlich machen ... die Klasse "Database" bzw. die DB räumt überflüssige Leerzeichen automatisch auf. Beispiel:

SELECT   EXP.*,
         cty.city AS city_name
FROM     tl_immo_expose AS EXP,
         tl_immo_city AS cty
WHERE    EXP.city = cty.id
AND      object_category = ?
AND      object_status = ?
AND      object_type LIKE ?
AND      cty.city LIKE ?
ORDER BY rooms ASC,
         stories ASC

ist lesbar und halbwegs nachvollziehbar, jedoch das gleiche Statement auf einer einzigen Zeile (mit mehr als 220 Zeichen) ist nicht mehr wartbar:

SELECT EXP.*,cty.city AS city_name FROM tl_immo_expose AS EXP,tl_immo_city AS cty WHERE EXP.city = cty.id AND object_category = ? AND object_status = ? AND object_type LIKE ? AND cty.city LIKE ? ORDER BY rooms ASC,stories ASC
Ansichten
Meine Werkzeuge

Contao Community Documentation

ich hook' mich gleich in die Abstraktion

Martin Mildner
In anderen Sprachen
Navigation
Verstehen
Verwenden
Entwickeln
Verschiedenes
Werkzeuge