Kommentera inte din kod!

Det här är ett ämne som delar oss programmerare i två väsenskilda läger; De som anser att man SKA kommentera i kod och de som anser att kommentarer är överflödiga.

Är du en duktig programmerare så kommer kommentarer att vara onödiga; du kan strukturera koden så att den blir lättläst och lätt att förstå. En dålig progammerare behöver kommentarer för att fylla upp sina kunskapsluckor, vilket egentligen bara gör att koden blir ännu mer svårläst. Dålig kod blir tyvärr inte bättre med kommentarer – snarare tvärtom. Ännu mer text att läsa för att förstå koden… Inte precis rätt väg att gå om man tänker lite logiskt på problemet. Bättre då att strukturera sin kod att den går att läsa och förstå lika lätt som en bok eller en tidning.

Vilka är då de vanligaste felen? Ja, i den kod som jag sett genom åren så är det följande:

Kommentaren kommenterar kod som är självklar

T.ex.

private double summery() {
double first = 1;
double second = 1;
//Returnera summan av first och second:
return first + second;
}

Vad i hela friden gör kommentaren för nytta där? Den gör bara att mängden text som ögat måste scanna igenom blir större och det tar längre tid för dig att läsa och förstå koden i sin helhet. Bort med sådana kommentarer!
Jag kan förstå att man lägger in sådana här kommentarer när man ägnar sig åt pseudo-kodning, men när man är klar med den riktiga koden så skall sådana kommentarer raderas!

Kommentar är helt felaktig


private double summary() {
double first = 1;
double second = 1;
//Returnera summan av first och second:
return first * second;
}

Här kommer man att hoppa till när man läser: Vad är det som är rätt? Är det kommentaren som är korrekt och koden felaktig eller tvärtom? Detta härrör sig troligtvis från att kommentaren en gång i tiden har varit helt korrekt, men sedan har förutsättningarna ändrats, koden har justerats, men kommentaren ligger kvar orörd.
Ta bort sådana här kommentarer i sin helhet! De kommer aldrig att uppdateras och skapar bara förvirring om vad som faktiskt gäller när man skall korrigera buggar, korrigera ändrade förutsättningar mm.

Det här felet är mycket vanligt i Java program och framförallt när programmeraren har använt editorns inbyggda funktion för att automatiskt lägga till en JavaDoc-stub. JavaDoc kommentarer har en förmåga att snabbt bli föråldrade och felaktiga. Ju mer programmeraren har lagt in i JavaDoc-kommentaren, desto större är risken att den innehåller felaktigheter. Så vilken nytta fyller då JavaDoc-kommentaren?

Kommentar ligger på fel plats

Inte så vanligt fel, men det inträffar. Man kan efter att ha kollat igenom hela koden kommit på att en viss kommentar faktiskt är felplacerad och borde ligga i en annan funktion eller på annan plats i koden. Detta inträffar då man har gjort ”klipp-och-klistra” kodning: Man har flyttat koden som kommentaren tillhör men inte själva kommentaren. Den ligger kvar på ursprunglig plats och detta skapar förvirring (återigen).

Men behövs aldrig kommentarer då?

Jo, det finns alltid undantag till alla regler. Det kan ibland hända att koden blir välidgt komplex och man behöver förklara vilken affärslogik som ligger bakom koden, eller helt enkelt en kommentar att ”det borde finnas ett bättre sätt att göra detta, men jag vet inte”. Dvs det kan finnas tillfällen då du känner på dig att koden är onödigt komplex, men du vet inte hur man skall kunna göra detta på bättre sätt. Då kan kommentaren fungera som en ”TODO”-minnesanteckning tills att du har hunnit fråga en kollega eller kollat upp på nätet. Men detta innebär att du har som mål att även eliminera denna kommentar!

Men det är väl bra att skriva JavaDoc så att användaren av min funktion vet vilka parametrar som förväntas och vad som kommer ut av funktionen?

Nej. En funktion med ett väldigt tydligt funktionsnamn som beskriver vad den gör, kommer att bättre tala om för mig vad det blir för resultat av funktion. De parametrar som behövs skall vara tydligt namngivna så att jag inte behöver fundera på vilken betydelse de har. Då behövs ingen JavaDoc. Om funktionen är så komplex att funktionen måste beskrivas, då behöver du troligtvis skriva om hela funktionens arkitektur. Något står inte rätt till då. Dessutom har jag sett allt för många exempel på JavaDoc som inte blivit uppdaterad då funktionen/klassen har blivit uppdaterad. Detta skapar förvirring. Funktionen/klassen kommer att utföra något på ett annat sätt än vad som är beskrivet i kommentaren. Vad är det som gäller? Resultatet eller kommentaren?

Ett litet test: Vilken av följande går snabbast att läsa och förstå?


/*
* This function will search all books
* in the database and return the author
* of a book with provided ISBN
*
* Parameter: searchISBN (String)
* Return: Name of Author (String)
*/
function String search(searchISBN) {
....
}

eller den här:


function String getAuthorOfBook(String ISBN) {
...
}

Annonser

Kommentera

Fyll i dina uppgifter nedan eller klicka på en ikon för att logga in:

WordPress.com Logo

Du kommenterar med ditt WordPress.com-konto. Logga ut / Ändra )

Twitter-bild

Du kommenterar med ditt Twitter-konto. Logga ut / Ändra )

Facebook-foto

Du kommenterar med ditt Facebook-konto. Logga ut / Ändra )

Google+ photo

Du kommenterar med ditt Google+-konto. Logga ut / Ändra )

Ansluter till %s

%d bloggare gillar detta: