Arbeitsmethodik, Dokumentation

[johny7]

Moin allerseits,

danke erst mal für die vielen Ratschläge.

Subversion, git, mercury o.ä., damit Du deine Sources und Scripte verwalten kannst

Yep.

Bugzilla ö.ä. für's Bug- und Feature-Tracking

(Trac faßt beides und noch einige andere Extras zusammen, z.B. ein Wiki)

Aha, interessant

Datenbank-Schema-Versionierung und automatische Up-/Downgrade-Scripts (siehe z.B. Pg::DatabaseManager für das Prinzip)

Makefiles oder Batches für automatische Installation / Updates / Downgrades

Das Update-System ist schon automatisiert

Mach nichts manuell, was Du automatisch laufen lassen kannst. Die Automatik kannst Du immer nachvollziehen, übermüdetes Gefrickel tief in der Nacht nicht.

Niemals auf dem Produktivsystem testen. Du hast Idealerweise vier Systeme:

Produktion -- wird nur automatisiert angefaßt, geht nicht kaputt

Staging -- Kopie der Produktion, der letzte Qualitätstest vor Produktion, geht idealerweise nicht kaputt, falls doch: zurück zum Test, Bugs beheben. Schnell wieder herstellbar. Wird unmittelbar vor dem Test auf den Stand der Produktion gebracht.

Test -- Kopie der Produktion, ausdrücklich zum Testen, geht regelmäßig kaputt. Schnell wieder herstellbar. Wird gelegentlich (vor und nach jedem Release) wieder auf den Stand der Produktion gebracht.

Development -- irgendwann mal (nach jedem Release) Kopie der Produktion, Entwicklungssystem, chronisch kaputt, schnell wiederherstellbar.

Staging und Test können virtuelle Maschinen sein, da bietet sich die Snapshot-Funktion zur schnellen Wiederherstellung an. Development kann auch eine VM sein, aber Repository (Subversion) und Bugtracking (Bugzilla) liegen außerhalb der VM.

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

Dokumentation: Je nach Kundenwunsch. ;-) Minimal so viel, dass Dein zukünftiges Selbst nie das Bedürfnis entwickelt, eine Zeitmaschine zu entwickeln, um in die Vergangenheit zu reisen und Deinem aktuellen Selbst wegen der Qualität und Quantität von Code und Dokumentation Schmerzen zuzufügen.

Besser so viel, dass Du das komplette Projekt an jemand anderen übergeben kannst.

Ideal:

Nur, was wirklich absolut und ohne jede Diskussion sofort offensichtlich ist, bleibt undokumentiert, z.B. $y=$x*$x;. Insbesondere, wenn Du trickst, Seiteneffekte nutzt, von bestimmten Voraussetzungen ausgehst, gehört minimal ein Kommentar in den Code.

$x=$x+1; # $x um 1 erhöhen

... ist redundanter Schrott.

# select kann hier nur maximal einen Datensatz liefern, weil die Spalte XYZ unique ist

... ist wesentlich besser.

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. Aber so viele Kommentare im Quellcode machen ihn unübersichtlich. 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?

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?

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

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...

Anforderungen, Entwürfe, Datenbank-Schemata, Algorithmen solltest Du natürlich auch dokumentieren und archivieren.

Wie? In OpenOffice-Dokumenten? Wie strukturiert und formatiert?

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!

"Doku schreib ich hinterher" funktioniert nicht. Nicht für eigene kleine Projekte und schon gar nicht für große Kundenprojekte. Denn Du wirst die Doku immer weiter vor Dir her schieben und irgendwann feststellen, dass Du Unmengen von undokumentiertem Code hast. Und wir alle wissen, dass Code nur ein ganz kleiner Teil eines Projektes ist, die Doku braucht viel mehr Zeit.

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.

Noch eins: Lohnt es sich, eine IDE wie z.B. Eclipse zu verwenden? Kann man damit die Dokumentation vereinfachen? Oder gibt es eine bessere Alternative? Oder reicht Notepad++?

Grüße, JN