Coding Guide

Mit Kommentaren sollte nicht gegeizt werden, alles was einem im Moment logisch und folgerichtig erscheint, ist schon am nächsten Morgen kryptisch.

Dateiübersicht

/** Angaben über File, Script, Klasse oder Funktion:
 *
 * Projekt: www.lehrling.biefer.com, Teil: php Lehrling
 * PHP Version: 5.3
 * kurze Beschreibung
 * Autor: marcel@biefer.com
 *
 * Bei Funktionen:
 * macht was
 * erwartet welche Attribute
 * gibt was zurück
 */

Grobstruktur durch Titel für Teile

#########################################
# vor grossem Codeblock wie Titel
#########################################

Feinstruktur durch Titel für Abschnitte

//------------------------------------------------------------------
// Komplexer Abschnitt wie Untertitel
//------------------------------------------------------------------

Abschnitte voneinander abgrenzen

//++++++
Abschnitt von + bis -
allerhand dazwischen
//------
oder

# A >>>>
Abschnitt von A bis A
allerhand dazwischen
dem Einfallsreichtum sind keine Grenzen gesetzt
# A <<<<

Detailstruktur in Zeilen

// was kommt
Befehl; // was war das

# unschädlich machen von Code // Test
# Code soll nicht ausgeführt werden // nächste Zeile besser 14.5.2012 mb

// :TODO: $name in Session schreiben

// :ACHTUNG: $prefix wird mit Datei xy eingelesen

Ansagen und Deklarieren

Am Dateianfang alle Voraussetzungen festlegen und offenlegen (siehe Kommentare):

1. Session
   ev. fortsetzen
2. Was macht die Datei
   Versions-Nummer
   Von wem erstellt
   Datei Stellung (Nutzer kommt von - geht nach)
   Wichtige Hinweise z.B. auf :TODO:
3. Externe Dateien einbinden
   require_once inc.klassen.php
   require_once inc.db_connection.php
4. Variable und Konstante initialisieren
   define ("KONSTANTE", 5); // Multiplikator
   $user = $_POST[]; // Benutzereingaben im Formular
   $intWahrenkorbArtikel = 0; // Warenkorb hat vorerst 0 Artikel
5. Funktionen
   function hallo() {...} // Begrüssung

Doppeltes auslagern

Beim Programmieren Redundanz vermeiden, voraus schauen. Was brauche ich, wo kann ich das auch noch nutzen?
Statt sich wiederholenden Code zu schreiben, eine Funktion verfertigen, die (mit veränderten Parametern) mehrmals aufgerufen werden kann.
Auch eine lange, ausführliche Bedingung kann der Übersicht halber in eine Funktion gesetzt werden und aus dem laufenden Code entsorgt werden.

Eine Anzahl immer wieder verwendeter Funktionen können in eine Bibliothek ausgelagert werden. Eine Bibliothek ist einfach nur eine Datei, in welcher eigene Funktionen definiert wurden und die dann mittels include_once() in ein, diese Funktionen benötigendes, Projekt eingebunden werden kann.

• Einzüge: vier Leehrschläge – keine Tabs
  
  

• Geschwungene Klammern: immer alleine auf neue Linie mit entsprechendem Einrücken
  function()
  {
  Befehle;
      if ()
      {
      Befehle;
      }
  }
  
  
• Geschwungene Klammern alternativ:
  if ($a != 2) {
      $a = 2;
  } else {
     $a = 7;
  }
  
  
• Abstände bei Zuweisungen:
  $a = array('Farbe' => 'rot', 'Geschmack' => 'süß'); // mit Leerschlägen
  
  
• Untereinander wenn möglich:
  $strZeilen = 'Du bist zu lang'
                    .'fuer eine Zeile';
  
  $short            = foo($bar);
  $long_variable = foo($baz);
  

Sprache

Open-Source-Applikation mit internationaler Beteiligung sollten statt Babylonisch Englisch nutzen. Aber für mich spricht nix dagegen deutsche oder französische Begriffe zu verwenden, im Gegenteil, die Gefahr, dass eine eigene Funktion gleich heisst, wie eine PHP Funktion, ist ausgeschaltet.

Namen

TypenbezeichnungTypenkürzel in Namen helfen zu erkennen, was beabsichtigt und erwartet wird. Diese Schreibweise wird als »ungarische Notation« bezeichnet.

• Variable: – Nomen verwenden, "camelCaps"
• String: $strZwergName
• Integer: $intAnzahlZwerge
• Fliesskomma: $fltZwergHoeheCentimeter
• Boolesche: $boolHatBezahlt
• Array: $arrAlleZwerge
• Funktion: readTextFromDB() – mit kleinem Verb beginnen, "camelCaps"
• Konstante: define LICHT_BLICK; – immer VERSAL und ohne Dollar, mit Underscors
• Superglobaler Array: $_POST[] – Underscore nach Dollar
• Klasse: class Class_Datum() – Nomen, mit Underscors
• Objekt: $Datum = new Class_Datum(); – Nomen, Gross beginnen, mit Underscors
• Datei: inc.DB_connect.php, funktion.Fehlerbehandlung.php – Endung immer *.php, zur Unterscheidung von eigenständigen und einzulesenden Dateien den Anfang des Dateinamens nutzen, dazwischen den Inhalt nennen.

Hinterher aufräumen

Abkürzungen meiden!
Den historisch gewachsenen Code sollte ich ausmisten, solange ich ihn noch verstehe. Sprechende Namen sind wichtig zum Verständniss. So schnell es beim Programmieren auch geht, sobald es läuft, sollte ich aus $Zw $intAnzahlZwerge machen.
Kandidaten zur Umbenennung sind Variablen, Funktionen und Methoden.

Vor allem bei Teamwork, wo sich Programmierer die Aufgaben teilen und gegenseitig im Code herum wusseln, ist es sinnvoll, sich strikte an Guidelines zu halten, die schriftlich niedergelegt wurden:

• >> http://pear.php.net/manual/de/standards.php
• >> http://framework.zend.com/manual/en/coding-standard.html
• >> http://www.buxaprojects.com/de/php_coding_guidelines.htm