Webdesign TYPO3 Duisburg Produktiv Killer Quelle Infoworld
Any fool can write code that a computer can understand. Good programmers write code that humans can understand. Zitat von Martin Fowler. Das hat er gesagt und da ist was dran. Natürlich können die Clean Coder hier wieder alles auffahren. Domain Driven Design heißt hier das Schlüsselwort. Das bringt die Begrifflichkeiten der Fachabteilungen in die Softwareentwicklung. Wie schon öfter gesagt stelle ich mich mit dem Clean Coder sehr schwer. Das ist hier ja jetzt auch alles nicht das Thema. Es geht hier um Dokumentation. Zu einer Dokumentation gehören sicherlich mehr als Kommentare im Quellcode. Das fängt bei der Projektbeschreibung an, geht über den Quellcode und die Entwicklungs- und Testumgebung bis hin zum Deployment. Auch Serverstrukturen und vieles mehr muß dokumentiert werden. In diesem Artikel der Produktivitätskiller für Programmierer gehe ich auf das Thema Quellcode Dokumentation ein. Da der Cowboy Developer alleine auf der Welt ist hält er genauso wenig von Kommentaren, wie der Clean Coder. Irgendwann mache ich da eine Comicreihe draus.
Dokumentation im Quellcode mit Kommentaren
Nennt man eine Klasse export mit der Methode doFullExport($dir) mit dem Parameter Directory braucht man das an dieser Stelle tatsächlich nicht weiter zu kommentieren. Das hier Laufzeit und Verzeichnisrechte ausreichend gesetzt sein müssen kann man sich auch noch selber herleiten. Der Teufel liegt allerdings auch hier im Detail. Der Special Case. Sagen wir bestimmte Verzeichnisse dürfen nicht importiert werden sollen. Es wird eine Protected var $aIgnoreDirs = array(‚.git‘, ‚.idea‘, ‚private‘); eingefügt. Das wäre dem Clean Coder ja nie passiert, aber der ist ja auch erst in 8 Wochen fertig ;). Dann kommt das Marketing und sagt der Kunde verlangt Ordner, die gar nicht existieren und andere sind zeitgesteuert. Zu allem Überfluß läuft alles über Sessions, wird aber auf ein AJAX Frontend umgestellt und braucht dann GET-Parameter. So was passiert. Die Application bläht sich auf. IF- und Switch-Statements kommen zusammen mit !in_array Abfragen. Natürlich sind das auch IF-Statements. Hier müssen Kommentare her.
Fazit zu Dokumentationen und Quellcode Kommentaren
Es ist wichtig seine eigene Leistung zu dokumentieren und transparent zu machen. Technische Dokumentationen sind wichtig, damit sich neue Mitarbeiter schnell einfinden können und Kollegen einen schnellen Einstieg finden. Hier gibt es Atlassian Confluence mit dem Wiki von eine tolle Möglichkeit. Im Quellcode muß auch dokumentiert werden, was da der Special Case ist. Gerade wenn es ausnahmen gibt. Hier können auch Jira Ticket IDs eingefügt werden, damit auch die Notwendigkeit nachvollzogen werden kann. Natürlich muß Quellcode trotzdem regelmäßig aufgeräumt und refaktorisiert werden.
