Kommentarer är av ondo

Om något står i en kommentar eller i en extern dokumentation spelar mindre roll, bara det står någonstans. Extern dokumentation är bättre för långa förklaringar av rena läslighetsskäl, men har nackdelen att den ännu lättare än kommentarer blir föråldrad och utdaterad, samt att den inte är lika omdelbart tillgänglig när man läser koden.

Jag kommenterar implementations detaljer vars syften inte är direkt uppenbara eller när jag känner att det kan vara behjälpligt. Ser inte hur det på något sätt är av ondo för någon, snarare tvärt om. Även i egna projekt som vuxit sig stora är det inte alltid lätt att ha koll på alla detaljer. Då kan en kommentar på rätt ställe var till stor nytta.

Det är lustigt att tro att en person som inte kan uttrycka en idé klart i kod skulle kunna göra det bättre med ett naturligt språk. Problemet är allt som oftast just att personen inte tänker klart innan de börjar.

Ett klart bättre alternativ till "förtydligande" kommentarer är automatiserade tester, som fungerar som en levande dokumentation. En kommentar, eftersom den inte kan köras, är en lögn som väntar på att hända.

TODO-typen av kommentarer gör sig bättre i ett ärendehanteringssystem, där det kan ses av alla och prioriteras av produktägaren.

En viktig funktion som kommentarer faktiskt kan fylla är strukturerade kommentarer som används för att automatiskt generera t.ex. en API-dokumentation.

Låter ju som ett dilemma.

"Dom är bra när det görs på rätt sätt."

Så, well, hur vanligt är det att det inte görs på rätt sätt? Och hur kan man förhindra att det missbrukas? Bättre utbildning?

Nu har jag ingen programmerare per-se, men finns det ingen oskriven regel som säger att kommentera inte det som framgfår av koden. Själv. Minns minns första kurs på universitet och det var obligatorisk att kommentera rikligt på sina inlämningsuppfigter. Slutresultatet blev att man hade massa kommentarer i stil med "/* Variabler */ -Detta var på civilingenjörsprogrammet i teknisk fysik. Resultatet blev det omvända mot var regeln skull illustrera.

På inledande programmeringskurser så brukar det alltid finnas krav på att man skall kommentera så in åt helvete mycket - och oftast fel saker.

Jag har jobbat som utvecklare i några år och tycker att man bör kommentera kod i vissa fall. All form av API bör dokumenteras så att man har en chans att använda en funktion/metod utan att behöva läsa 100 rader kod. Vissa delar av koden kommer vara komplicerad hur gärna man än vill att det inte ska vara det. Komplicerad kod bör dokumenteras för det hjälper nästkommande utvecklare förstå varför man tog ett beslut som vid första anblick kan se konstig ut.

Som erfarenhet så sitter jag på ett stort företag och jobbar med kod som började utvecklas för ca 20 år sedan. När man då stöter på en rad i stil med "double xt = xv * xc * 10.54;" så är det jäkligt trevligt att veta vad 10.54 representerar. Även om man skriver "double cogAngleAdjustment = 10.54;" så kan det fortfarande vara svårt att förstå varför det blev just 10.54.

Sist så vill jag tillägga att dom som säger "om man behöver kommentera kod så är man en dålig programmerare", kan aldrig ha jobbat i industrin eller åtminstånde bara jobbat på något nyare hot shot mjukvaruföretag. Det kryllar av dåliga programmerare och ingenjörer som inte är programmerare egentligen som skriver mängder med rader dålig kod varje år. Har dom då åtminstånde kommenterat koden så finns det kanske en liten chans att man lyckas förstå vad dom försökt åstadkomma inom en rimlig tid.

Det är för att det inte finns ett universellt svar

Olika utvecklare har olika preferenser, och olika företag har olika policy:s.

Alltså, att majoriteten av de som skriver kod är ganska kassa på det tror jag dom flesta här kan vara överens om.
Så när du behöver förstå vad denna dåligt skrivna koden faktiskt försöker göra är det ju djävligt nice att ha en kommentar som förklarar vad jeppen som skrev koden försökte åstadkomma tänker jag.

Jag menar, tänk dig att du ska sätta dig in i ett projekt som en idiot har jobbat på (personen i fråga vet inte att dom är en idiot), denna idiot delar dock din inställning ang kommentarer. Får du inte då oläsbar kod där det även är otydligt vad idioten faktiskt försökte åstadkomma?

Jag tänker att det borde vara lättare för en idiot att skriva en beskrivande kommentar än att bygga bra kod (även om många även misslyckas med kommentarer). Eller menar du att all sådan dokumentation bör vara skriven av idioten separat i wiki eller liknande?

Personligen håller jag med ditt tänk om diskussionen är helt och hållet ideologisk så att säga. Men precis som alla ideologier så är det mer ett önskvärt mål att sträva efter snarare än något som faktiskt fungerar i verkligheten förutom i undantagsfall.

Jag håller med, det är lite av en temporär-lösning atm, jag har tänkt byta ut "return null" till att kasta ett checked exception istället. Problemet var att jag behövde en snabb-fix till att där kastades unchecked exceptions från gson, och jag hatar verkligen unchecked exceptions i min kod, i just detta exemplet så dog hela min http-server eftersom runtime-exceptionet propagerades upp hela vägen och dödade min tråd eftersom det aldrig hanterades.