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.

Estic llegint: UML para programadores Java

De Robert C. Martin. 2004. Publicat per . 245 pàgines

Quan vaig veure aquest llibre a la prestatgeria d'una amiga li vaig demanar per llegir-lo. UML i Robert C. Martin em van semblar arguments prou forts com per a dedicar-li el meu temps. Després de la lectura no puc fer una altra cosa que desaconsellar-lo. I per dues raons.

Una traducció horrible
Quan llegeixo un llibre en anglès no entenc el 100% de les paraules. La majoria les agafes pel context i desprès de moltes repeticions acabes buscant-les al diccionari i aprenent alguna cosa nova. A més, els llibres tècnic no acostumen a portar moltes paraules noves. Quan veus algunes traduccions al castellà veus com clarament es justifica l'esforç de llegir en anglès.

En aquest llibre hi ha text, diagrames i codi. De vegades alguns dels elements del codi o dels diagrames els tradueixen i d'altres no. De vegades tradueixen codi que és d'alguna llibreria coneguda. De vegades en la mateixa porció del codi declaren alguna cosa en anglès però la referencien en castellà. Altres vegades et trobes traduccions massa literals. Has de fer contínuament una traducció al anglès del que vas llegint per mirar d'entendre què és el que va voler dir l'escriptor original.

I els traductors, de la ETSI d'informàtica de la Universitat de Valladolid, segur que ho podien fer molt millor. Quan veus el resultat final no pots pensar en una altra cosa que, o no han tingut temps, o no han tingut prou motivació.

Al començament del capítol 5, "Casos de uso", a la pàgina 60, podem trobar un exemple del text difícil de llegir que comentava:
«Los casos de uso son una idea maravillosa que ha sido sobrecomplicada ampliamente. Repetidas veces he visto equipos sitting and spinning en sus intentos por escribir casos de uso. Típicamente ellos thrash en temas de forma más que de fondo (substance).»

Un títol enganyós
Pot ser sóc massa ingenu en pensar que el llibre havia de tractar d'UML només pel títol. De fet el mateix autor (o això he entès a la traducció) es pregunta si val la pena un altre llibre d'UML desprès del meravellós UML Distilled de Martin Fowler (molt recomanable i curtet. No puc dir res de la traducció UML gota a gota). I és que aquest llibre dedica molt poques pàgines a UML.

Realment és un llibre de desenvolupament Java fent servir tecnologies àgils (més proper a l'Extreme Programming). Parla de proves unitàries, Test Driven Development i principis de disseny orientat a objectes. Dedica menys de 60 pàgines a UML i després el va aplicant una mica en els exemples.

Havent llegit d'altres de l'oncle Bob, els exemples d'aquest i la presentació d'UML resulten un complement força interessant. El codi que mostra i la manera com va aplicant les tècniques també val la pena. És una llàstima que la traducció faci que et quedi un regust amarg.

Java, orientació a objectes i la llosa del PL/SQL

Al capítol 6 del llibre Clean Code l'autor fa una reflexió sobre la diferència entre pensar en dades i pensar en objectes. Quan penses en dades t'interessa exposar les dades i et dóna el mateix el comportament. Quan penses en objectes, t'interessa exposar el comportament i amagar les dades tot el que puguis. Són oposats.

El Java és un llenguatge que et permet desenvolupar perfectament sense aprofitar de cap manera els beneficis de la orientació a objectes. Pots fer un programa perfectament procedural. De fet, molt del codi que vaig trobant és eminentment procedural. Poc a poc vaig trobant alguna aplicació de patrons, o com a mínim de disseny Orientat a Objectes, però no tant com hauria.

I me n'adono d'un altre perill. Als entorns on la base de dades Oracle és present és molt fàcil que una part del codi s'hagi desenvolupat en PL/SQL. És fàcil que hi hagin triggers i també que es facin servir procediments i funcions. Fins i tot que una part de la lògica d'accés a dades estigui encapsulada en aquest llenguatge.

Ja hem vist que pensar en estructures de dades i pensar en objectes comporten models mentals oposats. I és molt probable que els desenvolupadors que s'encarreguen del PL/SQL siguin els mateixos que s'encarreguen del Java, i quan toquen el Java és molt difícil que deixin la inèrcia de pensar en procedural.

En aquest sentit penso que el PL/SQL és una llosa pel bon desenvolupament Orientat a Objectes. Com a mínim cal tenir en compte aquesta dificultat, i el programador de PL/SQL ha de tenir clar que ha de fer un esforç especial amb la Orientació a Objectes.