Navigation überspringen

Deklarationen & Kommentare

Ziele

Allgemein

Es gilt

so wenig wie möglich, so viel wie unbedingt nötig kommentieren.

Variablen, die zu Beginn eines Quelltextes nur mit Hilfe eines langen Kommentars eingeführt werden können, sind in der Regel nicht den Konventionen entsprechend deklariert. Die PHP Community hält sich bislang zwar nicht an die Camel-Notation, jedoch gilt auch in der PHP-Programmierung "aussagekräftige Bezeichner sind zu wählen!".

Beispiel:

Die Funktion

array array_flip ( array $array )

ist zwar aussagekräftig, das heißt im Namen ist verborgen, was passeiren soll, jedoch entspricht die Deklaration nicht den modernen Standards.

Heutzutage würde die Funktion eher der etablierten Camel-Notation geschrieben:

array arrayFlip ( array $array )

Camel-Notation:

  • Bezeichner von Variablen, Funktionen, Methoden, Instanzvariablen beginnen kleingeschrieben, jedes folgende Wort im Bezeichner wird ohne underscore großgeschrieben angehängt.
  • Bezeichner von Klassen und Konstanten beginnen großgeschrieben.

Deklarationen

Beispiel:

Wir deklarieren eine Klasse, die sich um Zeiten allegemein kümmert.

<?php
/**
 * Description of Zeiten
 * @author T.Smit
 * @version 1.0 beta
 */
class Zeiten {
    private $timestamp;
    public static $MinutesPerHour=60;
    
    public function __construct($timestamp) {
        $this->timestamp = $timestamp;
    }
    public function getInitialTimestamp() {
        return $this->timestamp;
    }
    public function addDaysToInitialTimestamp($daysToAdd) {
        $dayToAdd = (int) $daysToAdd;
        return strtotime('+' . $dayToAdd . ' days', $this->timestamp);
    }
    public static function addDaysToTimestamp($daysToAdd, $Timestamp) {
        $dayToAdd = (int) $daysToAdd;
        return strtotime('+' . $dayToAdd . ' days', $Timestamp);
    }
    
}

//usage
$cZeiten=new Zeiten(time());
echo date('Y-m-d',$cZeiten->getInitialTimestamp()); //today
echo date('Y-m-d',$cZeiten->addDaysToInitialTimestamp(1)); //tomorrow
$arbitraryTimestamp=time();
echo date('Y-m-d',$Zeiten::addDaysToTimestamp(1,$arbitraryTimestamp)); //little later
?>

Auflösung:

  • die Klasse Zeiten wird großgeschrieben.
  • die Methoden-Bezeichner in den Zeilen 14,17,21 entsprechen der Camel-Notation.
  • in Zeile 9 wurde eine Konstante der Klasse Zeiten erzeugt. Sie wird nach Camel-Noation großgeschrieben.
  • in Zeile 21 wird ebenfalls eine statische Methode deklariert, durch die Mothodeneigenschaft wird sie aber kleingeschrieben.

Anmerkung:

In der PHP Community hat es sich eingebürgert, wenn die Camel-Notation angewendet wird, beginnen Instanzvariablen mit einem kleinen "c", siehe Zeile 29.

Kommentare

Im obigen Beispiel drücken die Bezeichner bereits eindeutig aus, was mit ihrem Einsatz zu bezwecken ist.

Kommentare dienen der Orientierung im Quelltext für spätere Wartung, Einarbeitung nachfolgender Programmierer oder zur Nennung von Verweisen.

Im obigen Beispiel ist im Bereich Zeile 2 bis Zeile 6 bereits der Blockkommentar verwendet. Dieser Kommentartyp wird verwendet zur Definition von Klassen und Methoden Programmbereichen mit besonderer Bewandnis.

<?php
/*
 * Kommentar Zeile 1
 * Kommentar Zeile 2
*/

?>

Der Zeilenkommentar ist, wie der Name schon ausdrückt, auf einzelne Zeilen beschränkt.

Negativ-Beispiel:

//Zähler für die folgende while-Schleife
$i=0;
#Die Schleife wird solange durchlaufen, bis $i größer 19 ist
while($i<20){
    echo $i;
    $i++;
}

Leider wird häufig, wie oben beschrieben, kommentiert.

  • Der Kommentar zum Zähler kann bei vernünftiger, aussagekräftiger Deklaration ausbleiben.
  • Der zweite Kommentar zur while-Schleife ist überflüssig, da jeder die Codezeilen versteht, der Zugang zum Quelltext erhalten sollte.

Lösung ohne Kommentare:

$iZaehler=0;
while($iZaehler<20){
    echo $iZaehler;
    $iZaehler++;
}