Arbeitsmethodik, Dokumentation

[Alexander (HH)]

Moin Moin!

Makefiles oder Batches für automatische Installation / Updates / Downgrades Das Update-System ist schon automatisiert

Inklusive Rollback (à la "oops, war nicht so gemeint, zurück zum alten Stand")?

Du hast Idealerweise vier Systeme:

Produktion -- [...]

Staging -- [...]

Test -- [...]

Development -- [...] Aha. Was spricht gegen drei Systeme? Ein Entwicklungsserver, eine Live-Umgebung und die Produktiv-Server?

Zwischen den letzten beiden sehe ich keinen begrifflichen Unterschied.

Welchen aus meiner Liste möchtest Du streichen? Staging oder Test? Der Charme einer Staging-Maschine ist, dass Du jederzeit eine Simulation des Produktivsystems hast (z.B. um "mal eben schnell" eine Präsentation zu zaubern, die der Chef bzw. Kunde vor 4 Wochen seinem Kunden bzw. Chef zugesagt hat, ohne Dich zu informieren). Natürlich kannst Du Staging und Test zusammenlegen, dann mußt Du aber nach erfolgreichen Tests die Test-Maschine erst einmal 100% auf den Produktionsstand bringen, und dann noch einmal das finale Update für das jeweilige Release dort testen.

Damit entsprechen die Server aber nicht dem Arbeitsablauf: Du programmierst auf der Development-Maschine (davon gibt es eine pro Code-Sklaven), irgendwann nennst Du einen Stand Release Candidate, baust ein Release, schmeißt das auf den Test-Server (einer für alle Code-Sklaven), und läßt es dort Amok laufen. Das wiederholst Du, bis ein Release Candidate den Test-Server nicht mehr schrottet und damit offiziell zum Release befördert ist. Das offizielle Release übergibst Du dann dem Admin (der Du in Personalunion auch sein kannst), der testet es noch einmal auf dem Staging-Server und spielt es dann in den Produktivserver ein. Demoliert das offizielle Release den Staging-Server, wird der Admin Dir kräftig den Kopf zurechtrücken, anschließend markierst Du das Release als blöde Idee und baust ein NEUES Release, während der Admin die Scherben des Staging-Servers zusammenfegt.

Plattenplatz ist billig, und VMs brauchen keine zusätzlichen Flächen. Was willst Du einsparen? Zwei Container weiter steht ein "erbeuteter" Server mit ordentlich RAM, auf dem laufen zur Zeit sieben VMs, notfalls auch mal parallel. Außerdem arbeitet der Server noch als SVN-Repository, Bugzilla-Datenbank, und (ein wenig, aufgrund unserer LAN-Struktur) als Fileserver für den Transfer zwischen realer und virtualisierter Welt.

Auf einem halbwegs aktuellen Desktop-System sind zwei parallel laufende VMs übrigens auch kein großes Thema.

Dokumentation: [...] Noch besser ist, wenn Du zu jedem Stück Programm noch eine richtige Dokumentation schreibst und die mit dem Programm synchron hältst. Die Doku gehört dann natürlich mit den Sources ins Repository. So! Das möchte ich. Ich weiß nur noch nicht, wie ich das anstellen soll! Hat jemand schon Lösungen? Wie kann ich parallel zum PProgrammieren dokumentieren? Und zwar in PHP? Am Liebsten würde ich gleich nach dem Schreiben der Funktion erklären, warum.

Ja, kann ich nachvollziehen. Das ist die "dunkle Seite der Macht".

Nach der reinen Lehre fängst Du mit einem Pflichtenheft an, daraus entwickelst Du ein grobes Konzept, daraus wiederum einen detailierten Plan. Drei Dokumente, die alle schon im SVN (oder git, hg, whatever ...) liegen, bevor Du auch nur eine Zeile Code schreibst.

Pflichtenheft: Was soll das Ding können? Unter welchen Bedingungen? Usw. Das Pflichtenheft kommt vom Kunden bzw. wird zusammen mit dem Kunden entwickelt.

Konzept: Wie setze ich das Pflichtenheft ganz grob um? Ablaufdiagramme wären hier zu finden, und Skizzen, wie Klassen / Module miteinander interagieren, wie Daten auf Tabellen aufgeteilt werden. Usw.

Plan: Wie setze ich das Konzept im Detail um? Hilfsklassen, Hilfstabellen, Methoden- und Funktionsnamen und -parameter, Beschreibungen, was Module / Klassen und Funktionen / Methoden im Detail machen sollen. Usw.

Notfalls unterteilst Du Konzept und Plan nocheinmal jeweils in grob und fein. Mit etwas Erfahrung kannst Du aus dem Grobkonzept schon abschätzen, wie viel Arbeit auf Dich zukommt, in der Größenordnung Wochen / Monate. Mit jedem Schritt kann Deine Schätzung besser werden, mit dem Feinplan kannst Du pro Funktion sagen, wie viele Minuten / Stunden Du brauchen wirst, und entsprechend aufsummieren.

Am Ende des Plans steht Dein fertiges Programm, so weit ausgearbeitet, dass Du nur noch von Deutsch / Englisch nach Perl, Java, PHP, SQL, HTML, Javascript, ... übersetzen mußt.

Wenn Du den Plan fertig hast, setzt Du als Einzelkämpfer den Entwickler-Hut ab und legst die Fußkette des Code-Sklaven an.

Der Job des Code-Sklaven ist wirklich nur noch übersetzen und interpretieren der feinen Nuancen, zwischen den Zeilen des Plans stehen.

Aber so viele Kommentare im Quellcode machen ihn unübersichtlich.

Nicht, wenn Du begriffen hast, das Kommentare keine Dokumentation sind. Manchen Leuten kann man das leicht beibringen, um andere Leute davon zu überzeugen, braucht man Werkzeuge aus mittelalterlichen Folterkammern.

Dokumentation schreibst Du nicht in Kommentare, sondern in ein eigenes Dokument, im Sonderfall POD notfalls auch in einen eigenen Abschnitt (am Ende) der Source-Datei.

Wie kann ich so eine History jeder Datei führen? Lohnt es sich, Excel-Tabellen dafür zu verwenden? So dass man auch Datum und Autor eintragen kann zu jeder Änderung?

Wozu doppelte Arbeit? SVN (git, hg, ...) kümmert sich um die Historie, komplett mit Datum und Autor und allen vorgenommenen Änderungen und Commit-Kommentaren.

Und wie kann ich einen Gesamtüberblick führen? So dass ich z.B. zentral aufgeführt habe, was ich alles zum nächsten Update des Produktivservers hochladen muss?

Darum kümmern sich Deine Scripte, das machst Du eben NICHT von Hand.

svn diff -r $oldRev:$newRev | grep Index

... kann ein Ansatz sein, auf dem ein Script aufsetzt.

Noch brutaler:

rm -rf tmpdir svn export [e-mail]:/svn/repos/projectX/tag/release-$Release tmpdir rsync -avzx --delete-during --rsh=ssh tmpdir/ [e-mail]/srv/www/projectX/ ssh [e-mail] make -C /srv/www/projectX after-rsync

Das lief fast exakt so sehr lange bei meinem letzten Arbeitgeber, einfach durch Aufruf von "make upload-production". Der gesamte Code liegt im SVN, den schmeißt svn export in ein frisches, leeres Verzeichnis. rsync schiebt den Code auf den Ziel-Server (je nach make-Target test, staging oder production), ohne dabei unnötig Bandbreite zu verschwenden, der abschließende Aufruf von make via ssh auf dem Ziel-Server sorgt dafür, das alle notwendigen Arbeiten automatisch stattfinden, z.B. DB-Updates, Restart persistenter Prozesse, usw.

Prinzipiell kannst Du nach dem svn export auch ein TAR / ZIP aus tmpdir bauen, das irgendwie anders zum Server schaffen und dort das Update-Script (hier: make after-rsync) laufen lassen.

Perls POD erlaubt es, die Dokumentation gleich mit in den Code zu schreiben und in nahezu beliebigen Formaten (man-Page, HTML, TeX, PDF, ASCII, ...) zu konvertieren. Ich brauch es halt für PHP und HTML sowie MySQL

Und? Wo ist das Problem? Finde ein brauchbares System, oder entwickle ein Neues. Zwei hab ich Dir vorgeschlagen, und Google wird Dir sicherlich noch ein paar mehr ausspucken.

Wenn Du Dich mit POD anfreunden kannst, hast Du drei Möglichkeiten:

• POD-Datei neben der zu dokumentierenden Datei (foo.php => foo.pod, exakt wie in Perl auch gerne praktiziert, oder foo.php => foo.php.pod)
• baue POD in die Datei ein und filter es wieder aus, bevor andere Tools mit dem Dateiinhalt arbeiten. Das hab ich neulich mal für SQL gebaut, im Kern unter 20 Zeilen Perl-Code. Die Kombination aus POD und SQL hab ich stumpf name.podsql genannt, Make und Perl haben daraus eine name.pod und eine name.sql generiert, und in einem weiteren Schritt aus der name.pod noch eine name.html.
• baue POD so in die Datei ein, dass es vom nächsten System ignoriert wird, z.B. als Kommentar oder als Dummy-Stringkonstante. Bei HTML könntest Du POD stumpf in <!-- --> verpacken, allerdings solltest Du das vielleicht nicht ungefiltert ins WWW stellen.

Javadoc generiert Teile der Dokumentation sogar selbst, kann aber ohne größere Verrenkungen nur gruseliges HTML generieren.

Ja, am Besten, man kann die Doku in verschiedenen Formaten bekommen...

Eben. Das ist für mich immer ein Argument für POD und gegen Javadoc und Derivate gewesen.

Anforderungen, Entwürfe, Datenbank-Schemata, Algorithmen solltest Du natürlich auch dokumentieren und archivieren. Wie? In OpenOffice-Dokumenten?

Office-Dokumente sind schwer zu diff-en, weil Binärmüll statt Klartext. Neuere Office-Formate sind zwar "nur" noch gezippte Sammlungen von viel XML und ggf. ein paar Bildern, aber auch die stellst Du als Binäres Archiv ins SVN und kannst dann ohne viel Theater keine brauchbaren Diffs bekommen.

Daher bevorzuge ich auch da POD oder notfalls HTML. Plain Text ist auch nicht schlimm. Du kannst auch TeX oder LaTeX für "hübsche" Dokumente nehmen, gerne auch wenn Du dich mit Formeln rumschlagen mußt (das kann TeX richtig gut).

Dazu ein Makefile, um aus POD, Plain Text, (La)Tex "vorstandstaugliche" Dokumente wie HTML oder PDF zu erzeugen.

HTML hat außerdem die Vorteile, dass Du erstens mit einem zentralen Stylesheet für ein gutes Aussehen der Doku sorgen und zweitens die einzelnen Bestandteile miteinander verlinken kannst -- selbst wenn einzelne Dokumente Plain Text, PDF oder gar eine Grafik sind.

Wie strukturiert

Wie es notwendig ist. Zum Beispiel mit einem doc-Verzeichnis im Projekt. Vielleicht noch ein zweites devel-doc-Verzeichnis, um Dokumentation für Kunde / End-Benutzer und interne Dokumentation zu trennen. Darunter nach Bedarf unterverzeichnisse.

und formatiert?

title, h1, h2, h3, ul, ol, dl?

Aus Erfahrung mit gewachsenen Projekten: Wenn Du nicht am ersten Tag anfängst zu dokumentieren und das konsequent durchziehst, wirst Du das Projekt nie auch nur näherungsweise vollständig Dokumentiert haben. Davor habe ich Angst. Deshalb frage ich lieber jetzt nach!

Fang an mit Doku. Code fällt hinten von ganz alleine raus. Siehe oben.

"Doku schreib ich hinterher" funktioniert nicht. [...]

An dem Punkt hat mein Vorgänger übrigens gekündigt, wir stehen hier mit 10 Jahren undokumentierter (und unqualifizierter) Bastelei an drei Projekten und alles brennt. Ich wünsch' mir zu Weihnachten übrigens nur eine Voodoo-Puppe mit seinem Gesicht ... ;-) Das will ich vermeiden.

Guter Plan.

Noch eins: Lohnt es sich, eine IDE wie z.B. Eclipse zu verwenden?

Ich kann mich mit Eclipse nicht so wirklich anfreunden. Andere wollen nie wieder ohne arbeiten. Wie auch emacs kannst Du Eclipse wahnsinnig aufbohren, wobei emacs da gerüchteweise noch etwas weiter anpaßbar ist. Eclipse braucht Java-Klassen, emacs kannst Du per Lisp-Scripting erweitern. Beides nicht sonderlich attraktiv ... ;-)

Kann man damit die Dokumentation vereinfachen?

Wie? Glaubst Du, Eclipse oder emacs schreibt die Doku für Dich? Ein HTML-Editor-Mode wäre natürlich hilfreich, wenn Du Deine Doku in HTML schreiben willst. Entsprechend ein POD-Mode für POD-Doku, LaTex-Mode, ...

Oder gibt es eine bessere Alternative? Oder reicht Notepad++?

Prinzipiell reicht Notepad++, den Rest kannst Du auch mit Scripten auf einem Linux-System erledigen. Allerdings gibt es leistungsfähigere Editoren, die Dir das Leben leichter machen. UltraEdit beispielsweise.

Ich persönlich bin nicht auf einen Editor festgelegt. Auf Windows-Systemen nehme ich meistens UltraEdit, gelegentlich auch Notepad++, wenn alle Stricke reißen auch mal das originale Notepad. Auf Linuxen hab ich meistens joe, notfalls nehme ich auch irgendeinen vi-Clone.

Alexander