Dokumentation i verkligheten

Jag säger "Som utvecklare är det viktigt att man dokumenterar det man gör. Speciellt på en arbetsplats med stor kodbas och gott om konsulter som kommer in och petar i den."

Snorvalpen: "Äh, bra kod dokumenterar sig själv."

Jag: "Sätt dig ner unge man, så ska jag berätta för dig om dokumentation i verkligheten"

Det som ska dokumenteras är inte i första hand koden själv. Istället dokumenterar man till exempel arkitekturen:

En kund använder version 4.2 av plattformen. De vill nu ha funktionaliteten APA. Att lyfta kunden till version 5.X är uteslutet av kostnadsskäl. Versioner 4.5 och 4.7-9 har bra stöd för APA men av dessa går 4.7-9 inte att kombinera med kundens databaslösning. Alltså måste vi lyfta kunden till 4.5 och inget annat. Hur vi håller reda på detta? Genom dokumentation. 

Man vill också dokumentera funktionalitet:

Den senaste releasen till kund var en katastrof och fick rullas tillbaka. För att upprätthålla förtroendet hos kunden satsas hårt på att den nya versionen ska vara klockren. Dock uppstår ett problem: ingen vet exakt hur systemet fungerar hos kund. I vissa tveksamma fall får utvecklingsgruppen rösta för att avgöra om något ska betecknas som "bug or feature". Därför dokumenterar vi funktionalitet.

Vi dokumenterar interaktioner med kunden:

En upprörd kund hör av sig och klagar på att funktionalitet BEPA, som de betalat dyra pengar för, slutat fungera. Efter en kort kodgranskning visar det sig bero på att någon för ett och ett halvt år sedan gjorde BEPA konfigurerbar och därefter stängde av den. Den upprörde kunden undrar varför. Eftersom någon inte längre finns kvar på företaget blir svaret "Förhoppningsvis för att någon från er bad om det". Därför dokumenteras kund-kontakter.

Ibland dokumenterar vi också den kod vi skriver:

Det är lätt att förstå vad värdet av konstanten m_dDelayStartupSec används till. Det är svårare att förstå varför den har värdet 4.0. Det är helt omöjligt att veta att om vi ändrar värdet på m_dDelayStartupSec här i applikation X, så måste vi också ändra motsvarande konstant i applikation Y annars kommer systemet att krascha vid start. Därför dokumenterar vi ibland även kod.