Els comentaris al codi menteixen

Quan vaig començar en el món de la programació creia que un bon codi era aquell que estava ben documentat, amb comentaris. Quan vaig descobrir el Javadoc vaig pensar que era un gran invent i, fins i tot, vaig fer servir en un projecte una eina de validació que m'informava si havia algun mètode sense comentari. Amb el temps em vaig anar adonant que menys del 5% dels mètodes tenien comentaris que aportessin alguna cosa: la majoria eren parafrasejats del nom del mètode o texts absurds per evitar que es disparessin les alertes de que faltava el comentari.

Al llibre de Clean Code hi ha una anàlisi molt interessant dels comentaris al codi. En Robert C. Martin fa una afirmació categòrica: Els comentaris menteixen. Al més pur estil House.
Els programadors no tenen temps per mantenir els comentaris. Si els comentaris no estan bé el codi pot funcionar igual de bé, i no alertarà el compilador d'aquest fet. I com no pot haver control més enllà de la voluntat, amb el temps els comentaris s'allunyen tant de la intenció original que arriben a ser perjudicials.

L'oncle Bob proposa desenvolupar el codi de manera que sigui molt expressiu. Fer servir noms de mètodes i de variables molt clars, i variables intermitges si s'escau. El codi ha de ser prou clar. Si cal un comentari, mira com pots canviar el codi per que no sigui necessari.

Tots els comentaris són dolents per definició, doncs? No. Segons el llibre Clean Code, quis serien els comentaris acceptables?
De vegades és necessari explicar per què fas servir una estratègia concreta, o per aclarir. Els comentaris de coses per fer (els TODO) també són molt útils. I també són útils els JavaDoc de les API públiques. Però no facis més comentaris dels que puguis mantenir.

Com a comentaris dolents posa un bon grapat d'exemples. Llegint-los te n'adones que de vegades has estat autor d'algun d'aquests: Comentaris redundants, comentaris absurds als getters i setters, comentaris per farcir, el que estàs rumiant (per que no ho tens clar), l'històric dels canvis (ja tens l'eina de control de versions), indicador de final de clau (o el END en altres llenguatges), marcador d'on comencen els mètodes d'un determinat tipus, codi comentat per que no es fa servir, ...

Trobo molt útil, com a reflexió, pensar dues vegades abans de posar un comentari al codi.

Per cert, em van passar un enllaç sobre comentaris divertits al codi. N'hi ha per partir-se.