Besser PHP programmieren

PHP ist eine Programmiersprache, die man schnell lernt und mit der man einfache Programmieraufgaben in kurzer Zeit erfolgreich umsetzen kann. Nach den ersten Gehversuchen und der Übernahme grösserer Projekte kommt man jedoch schnell ins Straucheln, wenn man nicht über Grundkenntnisse des Programmierens verfügt. Genau auf dieses Bedürfnis antwortet das Buch von Carsten Möhrke. Besser PHP programmieren bietet Know-how und Hintergrundinformationen zur Theorie des Programmierens und Lösungsansätze aus der Praxis. Darunter finden sich viele grundsätzliche Informationen zum Umgang mit PHP, die selbst erfahrene Programmier nicht kennen. Angefangen vom Programmierstil und dem Aufbau von Programmen über Modularisierung, dem Einsatz von PEAR, Model-View-Controller-Architekturen, Eclipse, Frameworks, der Dokumentation und der Kommentierung der Software sowie Fragen der Performance und der Sicherheit. Dieses Buch ist keine Rezeptesammlung, sondern ein Buch für den täglichen Einsatz in der PHP-Küche.


Leseprobe:

8 Dokumentation (S. 459-460)

Die Dokumentation eines Projekts ist immer wieder ein leidiges Thema. Der Entwickler glaubt, er müsse nichts dokumentieren, da er es doch selbst programmiert hat und somit auch versteht. Der Kunde hätte zwar gern eine Dokumentation, möchte sie aber nicht bezahlen. Nun, der Projektleiter weiß zwar, dass eine Dokumentation wichtig wäre, aber solange der Kunde dafür nicht bezahlt, rechnet sie sich nicht – zumindest nicht auf den ersten Blick. Sie merken schon, es gibt eine Menge Gründe, die gegen eine Dokumentation sprechen. Trotzdem gibt es aber auch viele Gründe, die für eine gute Dokumentation sprechen:

- Auch ein Entwickler ist vergesslich – nur weil er jetzt weiß, was eine Funktion leistet, heißt das nicht, dass er das in ein paar Wochen noch weiß. Das trifft insbesondere auch auf Zeilen zu, in denen der Code optimiert wurde.

- Programmierer lernen dazu – Code, der jetzt noch absolut logisch erscheint, kann in einigen Wochen schon unlogisch erscheinen.

- Programmierung ist meist Teamarbeit, und die setzt voraus, dass jeder auf den Code des anderen aufsetzen kann. Das wiederum setzt voraus, dass der Code nicht erst analysiert werden muss.

- Projektmanager können und dürfen nicht riskieren, dass die einzige Dokumentation im Kopf des Programmierers steckt. Wird er krank, kündigt er oder – noch schlimmer – geht zur Konkurrenz, ist das Projekt häufig gescheitert und der Kunde verloren.

- Auftraggeber sollten auch ein vitales Interesse an einer guten Dokumentation haben. Sollte ein Kunde den Dienstleister wechseln wollen oder müssen, kann ein anderes Entwicklerteam nur mit entsprechender Dokumentation weiterarbeiten.

8.1 Anforderungen an eine Dokumentation

Es kann verschiedene Arten von Dokumentationen geben – zum Beispiel ein Anwenderhandbuch, eine Anleitung zur Installation oder eine Entwicklerdokumentation. Da es in diesem Buch um die Programmierung geht, wird hier auch nur das Entwicklerhandbuch betrachtet. In ihm wird all das erläutert, was zum Verständnis der Anwendung wichtig ist. Wenig bekannt ist, dass es hierfür sogar DIN-Normen gibt. Hierbei handelt es sich um:
- DIN 66230 – Programmdokumentation
- DIN 66231 – Programmentwicklungsdokumentation
- DIN 66232 – Datendokumentation

Da diese Normen sehr umfangreich sind, gehe ich hier nur auf die wichtigsten Aspekte einer Dokumentation ein. Gleichwohl kann ich Ihnen nur empfehlen, einmal in diesen Normen zu stöbern, da sie durchaus lehrreich sind.

Eine Dokumentation sollte knapp, aber präzise sein und vor allem auf alle wichtigen Details eingehen. Am Anfang einer Dokumentation steht ein einleitender Teil, der dem Leser einen schnellen Überblick verschaffen soll. Die Informationen sind hier noch nicht sehr konkret und werden später vertieft. Darauf folgt die Aufgabenstellung.

Das heißt: Welches Problem soll mithilfe der Anwendung gelöst werden? Hierunter fallen auch spezielle Kundenanforderungen wie Verschlüsselung, Barrierefreiheit oder Ähnliches. Dies ist wichtig, um später zu verstehen, welchen Funktionsumfang die Anwendung abdeckt und warum sie das tut.

Der zweite wichtige Punkt ist die Ausgangsvoraussetzung. Hier wird alles beschrieben, was kundenseitig zur Verfügung gestellt wird und Ihre Arbeit beeinflusst. Hierzu gehört zum Beispiel, woher Sie Daten übernehmen und in welchem Format diese vorliegen. Vergessen Sie dabei auch nicht, eventuell relevante Versionsnummern zu erwähnen. Wenn Ihr Programm darauf ausgelegt ist, Daten in XML 1.0 zu verarbeiten, kann es mit Version 1.1 schon zu Problemen kommen.1 Sie sollten auch hier noch nicht zu konkret werden. Es geht hier nur darum, dem Leser einen schnellen Überblick zu verschaffen.