Kommentarer i kode er en uting, og med bruken av AI har dette blitt mye verre.

For en god stund siden var jeg i et prosjekt der “Alt som kunne ha JavaDoc, skulle ha JavaDoc”. Da kom jeg over denne herlige kodesnutten:

/**
 * @return always false
 */
public boolean isEnabled() {
  return true;
}

Siden har jeg vært temmelig skeptisk til kommentarer i kode. Det finnes også forskning som tilsier “less is more”.

Kommentarer i kode, et område AI gjør helt feil

Det siste halvåret har jeg brukt AI på jobb, og det har gjort meg noe mer produktiv. Av og til er resultatene fantastiske, andre ganger hadde jeg klart det like raskt selv, og noen ganger leder AI meg på ville veier. Dette blir nok bedre med tiden, så det er viktig at vi lærer å bruke AI effektivt. Men akkurat nå er nøkkelen å raskt gjenkjenne når AI-løsninger ikke fungerer, og heller fikse det selv. Jeg har mange eksempler på begge deler.

Et område hvor jeg mener AI er tilnærmet ubrukelig, er hvordan det insisterer på å legge igjen masse kommentarer i kode. Disse er ofte helt unødvendig. F.eks.

  const handleAddNewForm = (): void => {
    // Reset the new item to default values
    setNewItem(createEmptyItem());
    // Show the form
    setShowNewItemForm(true);
  };

Funksjonene kunne muligens ha litt bedre navn, men dette er klassisk AI generert kode. Gjør det koden bedre, øker det lesbarheten?

Det er dessverre ikke uvanlig at ved vedlikehold av kode, så oppdateres kode men ikke kommentarer. I så fall blir kommentarene misvisende, om ikke direkte løgnaktige. Jeg har selv kommet over kommentarer som jeg har latt stå, selv om jeg innerst inne vet de lyver, fordi jeg blir usikker. Jeg er ganske sikker på at enkelte kan stole mer på kommentarene enn koden. Jeg har i hvert fall opplevd ganske sterk kognitiv dissonans når kommentarer og kode ikke stemmer overens.

En studie viser at kode med inkonsistente kommentarer er cirka 1,5 ganger mer sannsynlig å inneholde bugs sammenlignet med konsistente kommentarer (Investigating the Impact of Code Comment Inconsistency on Bug Introduction).

En bedre måte å bruke AI

AI er faktisk veldig bra til å forstå kode. Så om du kommer over kode, med eller uten kommentarer, som du sliter å forstå, bare mat det inn i AI. Den vil som regel være ganske spot on til å hjelpe deg forstå koden. Så rett og slett dropp kommentarene i kode.

Dette for øvrig mine AI instruksjoner (.augment-guidelines):

1. Always be critical
2. No comments in code whatsoever unless the code is extremely unusual and impossible to understand without explanation
3. Don't praise ideas unless they're genuinely innovative or solve problems in an elegant way
4. Don't apologize for mistakes
5. It is better to just say you don't know than to hallucinate an answer
6. Always think of three possible solutions before implementing anything
7. Keep code examples as concise as possible
8. Always follow the project's existing code style
9. Make your edits lightweight
10. Prefer writing code in functional style

Jeg vurderer nå å endre 2. til No comments in code, whatsoever.

Det riktige stedet å skrive kommentarer

Jeg har behov for å kommentere koden min. Av og til mye, av og til lite. Og det finnes et helt perfekt sted å gjøre dette, i commit meldinger. Her må du gjerne skrive en essay om hva du har gjort, og ikke minst hvorfor du gjorde det.

Dette er det riktige stedet og den riktige tiden å kommentere det du har gjort.

Slik ser min git commit template ut:

# If this commit is applied, it will... -------------------72 chars----|


# What is this ? Why was this change made? ------------------------80 chars----|

Oppsummert

Kommentarer lyver. AI gjør det verre. Løsningen? Skriv selvforklarende kode og la AI hjelpe deg forstå kode når du trenger det - ikke lage mer rot.

Claude er for øvrig helt enig med meg.