Vem som helst kan skriva kod som en dator kan förstå men det är en konst att skriva kod som en människa kan förstå. För att försöka få en människa att förstå vår kod brukar vi förmedla detta i onödiga kommentarer; vi klottrar helt enkelt ner vår kod för att försöka förklara för andra och för oss själva vad vår kod gör.

Jag vågar hävda att vi gör detta för vi inte kan skriva bra kod. Vi är inte säkra på att vi förstår koden nästa gång vi vill ändra i den och försöker därför berätta vad koden gör med hjälp av text. Det blir inte mer underlättande för oss själva eller andra, istället krånglar vi oftast till det för oss. Så fort en kommentar måste skrivas så vet vi att koden är otydlig.

Vi utvecklare vill gärna läsa koden som om det vore en uppsats, vi vill läsa och förstå vad den gör genom självbeskrivande metodnamn, självbeskrivande klassnamn m.m.

Underhåll av kommentarer är också ett vanligt problem vi har: Vem orkar läsa och underhålla en sjö med kommenterar? Hur vet vi att våra kommentarer talar sanning? Jag kan garantera att över hälften av all kod som idag är fyllda med kommentarer faktiskt ljuger för oss.

Det är faktiskt bättre att inte ha kommentarer alls än att ha en massa som ljuger för oss. Vad händer om vi inte läser koden? Hur vet vi då att de är sanna? Varför skall vi läsa både kommentarer och kod när vi faktiskt kan skriva självförklarande kod? Vi vill inte läsa en massa onödig text som vi ändå inte vågar förlitas oss på.

Ett annat problem som kan uppstå är att det Ibland skrivs fler rader kommentarer än kod. Vi tappar oftast tid och fokus genom underhållsarbetet av kommentarer.

Majoriteten utvecklare tycker inte ens om att kommentera, speciellt inte underhålla andras kommentarer och det är då de oftast förblir felaktiga. Det är också mycket vanligt att vi inte hinner dokumentera pga. tidsbrist.

Ett annat mönster som oftast syns i dålig kod är otydliga metodnamn. Istället för att ändra metodnamnet låter vi en kommentar förklarar vad metoden gör.

Försök se kommentarer som en varning, försök förtydliga koden med ett bättre namn istället, det är oftast där problemet ligger.

Vill du exempelvis kommentera en loop inuti din kod, refaktorera loopen och lägg den i en metod med ett förklarande namn istället. Refaktoring är viktigt, den görs för att förtydliga koden, minska antal rader kod, samt för att ta bort dubblerande kod.

En viss typ av dokumentation måste dock finnas, men den skall vara i ett separat dokument och dokumentationen skall vara kort och enkel och förklara designen och inte tekniken. Tekniken har vi redan läsbar genom vår kod. Ingen vill läsa flera hundra sidor dokument. Det finns en regel som säger:

”Skriv dokumentation om du måste men bara om den verkligen gör någon nytta!”

GOD JUL & GOTT NYTT ÅR