Ich weiss nicht, wie lange ich es schon vor mir hergeschoben habe, meine alten PHP Projekte zu debuggen und auf aktuelle Standards zu bringen. Damit man seinen eigenen Code nicht stundenlang nach dem Sinn der Funktionen durchsucht ist Dokumentation das A und O – ich weiss wovon ich rede, da ich den gestrigen Tag damit verbracht habe, grosse Teile meiner Software aufgrund mangelnder Kommentare und Erklärungen neu geschrieben habe…

Es ist nicht wichtig, einen Roman zu schreiben. Ich habe mir folgenden Standard angewöhnt (von JavaDoc geklaut):

MyExampleFnc($a as string, $b) {
/*************************************
Function:      My example function
Description:   This is just an exampe
               that does nothing.
Parameters:    $a - string, example input string
               $b - variant, another example
Output:        Function does this and that...
**************************************/
...
}

Was ich hier dokumentiere ist einfach erklärt: Function ist der lange Name einer Funktion, da man ab und an Namen vergibt, welche später nicht nachvollziehbar sind. Die Description ist eine kurze Beschreibung der Funktion, was sie tut. Parameters bezeichnet eine Liste, welche Argumente die Funktion annimmt und eine kleine Beschreibung ihrer. Der Output ist dann das, was die Funktion zurückgibt. Damit ist es möglich, in kurzer Zeit die gesamte Funktion neu zu schreiben, ohne sich erst stundenlang Gedanken darüber zu machen, was es zu beachten gibt. Vergeudet keine Zeit – Kommentiert :)