Keep on Balping Balp Skiver Om allt och alla…

Dokumentera!

Att skriva bra kod är inte bara att skriva in något i ett programspråk som kompilatorn fattar. Det är så mycket mer, ett av det svåra komplexa områden som ofta diskuteras och kan leda till flame-wars mellan utvecklare är dokumentation. Inom detta som så mycket annat när det gäller programmering
finns det inte ett rätt sätt, utan massa saker kan vara rätt. Jag tänker ta upp några principer som jag tycker är extremt viktiga.
Andra bloggar om: programering, kodstandard, dokumentation

Närhet

Kod och dokumentation skall vara nära varandra. Både att läsa och att uppdatera. Är det inte detta kommer man inte att använda sig av den och inte se till att den är korrekt. Som en följd av detta förordar jag att alldokumentation bör ligga i koden, eller så nära som möjligt.

Korrekthet

Felaktig dokumentation är ofta farligare och jobbigare än ingen dokumentation. Vi tenderar att tro på det som står skrivet, även om koden säger något annat.

Duplicering

All duplicerad kod och dokumentation innebär att den ena kopiean kommer att vara ouppdaterad vi ett eller annat tillfälle. Detta ger oss problem med vilken av versionerna som är korrekt.

Konsis

Skriver det som behövs, och bara det som behövs, massa extra text göt bara att det är svårare att få överblick.

Varför inte hur

Koden beskriver redan hur, att upprepa detta i dokumentationen är onödigt. Koden skall kunna läsas enkelt i alla fall. Varför man valt en viss lösning står inte i koden. Utan förklaring om varför kommer man att festats att testa den andra lösningen om och om igen med samma resultat.

Vad inte hur

Beskriv funktioner, och klasser med vad de skall göra, vilket syfte det har. Vilka ansvars områden de har, inte hur de uppfyller detta. Men för detta finns det saker i hur som kan påverka hur det används skriv in detta med varför det är så.

Popularity: 2% [?]