Webdesign TYPO3 Duisburg Produktiv Killer Quelle Infoworld
In diesem Artikel gehe ich wieder auf die Dokumentation im Quellcode von PHP-Projekten ein. Wie schon in Zu wenig Dokumentation aus der Artikelreihe Produktivkiller für Programmierer erwähnt gehört zu einer Dokumentation mehr als nur PHP Quellcode. Ehrlich gesagt ist mir zu viel Dokumentation in meinem Leben noch nicht begegnet. Falsche Dokumentation oder nichts aussagende hingegen schon. Ich führe hier mal 3 Beispiele auf, die ich mir heute ausgedacht habe.
Zu wenig Aussagende Dokumentation
//Array with the directories
Zu viel Dokumentation
// This is an array. Later in the application there is a if(!in_array($aIgnoreDirs)) Statement to check if the loop detects one of its elements and will continue the export loop
Richtige Dokumentation
// Array with ignored export folders continue the export loop in doExport() Method
Variable im PHP Quellcode
$aIgnoreDirs = array(‚foo‘, ‚bar‘, ‚private‘);
Natürlich hat hier jeder auch ein seine eigene Meinung zu dem Thema. An der Stelle ist es auch nicht wirklich nötig einen Kommentar einzufügen. Der Variablen Name ist sehr aussagekräftig. Noch besser wäre hier ein $aDirsIgnore. Dadurch wären in der IDE wie z.B. Phpstorm bei der Autovervollständigung alle Arrays mit Directory Angaben zusammen gruppiert und gelistet. Ich finde das sehr praktisch, aber es nicht für jeden etwas.
Fazit zu Too much documentation
Das Thema dieses Artikels ist auch nicht Clean Code. Hier gibt es leider auch keine Universalantwort. Da muß man sich im Team drauf einigen. Es gibt Codestandards, die sich auch mit den Kommentaren beschäftigen. Die gängigen Standards PSR-1 und PSR-2 prüfen allerdings nicht ausreichend, damit die Phpdoc Vorgaben ausreichend geprüft werden. Hier ist der Squiz Standard sehr nützlich, allerdings prüft er insgesamt viel zu viel. Ein Standard macht allerdings noch lange keinen guten Programmierstil. Übersichtlicher und guter Quellcode ist eine wichtige Sache, damit Programmierer effizient bleiben. Sehr wichtig ist hier das Refactoring von Quellcode. Dokumentation sollte ausreichend vorhanden sein. Mit den heutigen IDEs ist das ja auch alles kein Hexenwerk mehr.
