C1-C5

Försöker att beskriva reglerna C1 till C5

• C1: Fel information i fel system
• C2: Felaktiga kommentarer
• C3: Onödiga kommentarer
• C4: Dåligt skrivna kommentarer
• C5: Bortkommenterad kod

C1: Fel information i fel system
Första frågan man måste fråga sig är vilka kommentarer som är lämpliga att ha i programmeringskod. Är det verkligen relevant att ha en kommentar som säger att ändringen utfördes för bugg #34 eller att ha en lista med de 20 senaste ändringarna? Regeln jag följer är att alla kommentarer i koden ska beskriva koden och inte versionenhantering, ärendehantering eller något annat som bör hanteras av system utanför koden. Tex bör ett bra ärendehanteringssystem hålla reda på vilka ändringar i källkoden som gjorts för ett ärende. Det borde inte vara något som ska stå i källkoden.

C2: Felaktiga kommentarer
Vem av oss har inte läst en kommentar som har skickat ut oss på någon timme av felsökning i fel ände av problemet för att koden har förändrat men inte kommentarern. Felaktiga kommentarer förstör värdet av flera hundra bra då de rubbar förtroendet för hela applikationen. Vågar jag verkligen lita på det som står där?

C3: Onödiga kommentarer
De av er som använder Visual Studio har säkert hört talas om Ghostdoc. Det är en liten plugin som utifrån en metodsignatur skapar kommentar. Problemet med Ghostdoc är att de kommentarer som programmet skriver inte tillför något utan enbart är en upprepning av den information som står i metodsignaturer. Det enda som tillförs är fler rader av kod som måste underhållas. Fler kommentarer som efter en ändring riskerar att att ljuga för läsaren. Slutsatsen bör alltså vara att om du inte tänker bidra med något som inte redan står i koden bör du hellre låta bli att skriva kommentaren i första läget. Nu är det säkert något som undrar hur dokumentationssystem som tex javadoc ska hanteras, då de använder formaterade kommentarer för att extrahera ur infomation från källkoden. Svaret hittar vi i C1. Det vore kanske bättre att ha något annat system för att hantera den typen av information.

C4: Dåligt skrivna kommentarer
När man skriver kommentarer ska man inte göra det slentrianmässigt tex som vid användade av Ghostdoc. En kommentar bör värderas högt och man bör lägga en hel del möda på att skriva kommentaren så bra det går. Vad är en dålig kommentar? Den är ju inte felaktig som i C2. En dålig kommentar kan vara felaktigt placerad, vara oprecis och eller onyanserad. Den kanske bara delvis är relevant.Vad ska man göra med en dålig kommentar? Man lämnar den naturligtvis inte det dåliga skicket utan ser till att det antingen blir en bra kommentar eller en raderad kommentar (som man får hitta i versionshanteringssystemet).

C5: Bortkommenterad kod
Här finns det inga ursäkter. Använd ett versionshanteringssystem om ni har ringaste intresse av att den bortkommenterade koden ska gå att återfinna. Så kort och gott, bort med skiten, bortkommenterad kod har inte i en källkodsfil att göra.