Arbeitsmethodik, Dokumentation

[Alexander (HH)]

Moin Moin!

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

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

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

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

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.

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.

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.

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

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

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.

"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 ... ;-)

Alexander