La doctrina del comentario

Hoy voy a hablar del comentar o no comentar el código, que parece que se está convirtiendo en una doctrina.

¿Qué es lo que ocurre? Vengo observando un tiempo la tradicional defensa del comentario como algo necesario, pero que hay que controlar en tamaño (nº de comentarios respecto al código), forma (estándares), etc.

Por otro lado, está la defensa a ultranza de la total ausencia de comentarios. Ojo, porque aquí sí que se suelen excluir los comentarios JavaDoc o NDoc que suele haber al principio de las clases y que se utilizan principalmente para documentar el código. Esto, menos mal, parece que nadie lo pone en duda (o al menos, no he identificado un grupo que esté por la labor de eliminarlo).

A continuación, veremos algunos argumentos o doctrinas que la gente utiliza en sus blogs en internet, y que me parecen interesantes. No los copio aquí para ensalzar ni tampoco ridiculizar a sus autores, sino sólo para intentar entender este tipo de argumentos y poder entender de qué hablamos. El objetivo no es tanto quitar la razón a los que están en contra de los comentarios, sino más bien entender el porqué de su postura, y tratar de ir un poco más allá. Yo de momento, sí me declaro abiertamente defensor de comentar el código, aunque luego hablaremos de con qué matices (mmm veo que de aquí tengo material para otro artículo de enfermedades del software: la "comentaritis"). Siempre creo que "menos es más".

Frases en contra o a favor de los comentarios que podemos encontrar por la web:

• Usar comentarios va en contra de mis principios.
• los comentarios son siempre "el patito feo" del código fuente, cuando en realidad son tan importantes como el resto
• comentar antes de programar, es lo que todo programador debe hacer. No puedes lanzarte a programar sin saber lo que quieres lograr.
• al desarrollador por lo general no nos gusta "perder el tiempo" comentando y mucho menos documentando
• si lo he hecho yo, ya sabré porqué lo he hecho
• los comentarios en el código son algo completamente inútil que no hacen más que entorpecer y causar problemas
• Cuando el código es modificado, tenemos que modificar también los comentarios, pues corremos el riesgo a explicar algo que no es lo que estamos haciendo. Ya bastante trabajo resulta mantener un código para también tener que mantener un paquete de oraciones.
• Provocan problemas culturales, ya que muchas veces los comentarios están en un idioma diferente al que es capaz de leer el desarrollador actual, o en la mejor intención de hacerse entender, el "escritor" dejó una lista de oraciones sin concordancia, sentido, y con cientos de faltas de ortografía y errores gramaticales.
• El que un comentario parezca necesario es signo de que el código no es lo suficientemente claro. Un buen código debe siempre explicarse por sí mismo sin necesidad de un "bastón" (o comentario).
• Reducen la claridad en el código. ¿Alguna vez han visto un método con 50 líneas de las cuales menos de 10 son de código y lo otro es todo un tratado científico? Yo sí, y resulta un verdadero dolor de espalda descubrir las líneas reales ejecutables entre tantas palabras
• Esta técnica de crear métodos para aislar secciones de código y dejar bien clara su función es extremadamente útil para aumentar la claridad. En vez de tener un módulo con 500 líneas ejecutables, podemos dividirlo en varios métodos cuya responsabilidad esté bien delimitada. El resultado final será mucho más claro y flexible.
• los comentarios son la prostitución de las incapacidades de un programador.

¿Qué radicales son algunos de los comentarios, verdad? Y no es para menos. Por desgracia, es frecuente encontrarse programadores poco experimentados en los equipos que acaban sufriendo de "comentitis": lo llenan todo de comentarios por su inseguridad y falta de método. Aquí os recomendaría los que a mi modo de ver son dos libros indispensables tanto para programadores que se creen experimentados, como para los que empiezan. (Creedme, nunca seremos suficientemente experimentados, y lo que es peor, el paso del tiempo, la destreza se pierde). Los libros son:

• Code Complete, de Steve McConnell
• Clean Code, de Robert C. Martin

Dejaremos para otro día unas recomendaciones sobre qué y cómo comentar, y porqué. Ahora vamos a dar un breve repaso a algunos consejos para evitar que nos afecte:

• No podemos controlar todo lo que hacen los demás. No podemos exigir que respeten nuestra forma de trabajar si no respetamos la de los demás. No todo el mundo tenemos el mismo nivel técnico.
• Si algo te molesta, dilo. Pero ten respeto por las personas y su trabajo. Además, te encontrarás con que quizás a ese programador le obligaron a hacerlo así, o quizás era su primer trabajo (todos hemos tenido un primer trabajo, y un segundo trabajo).
• Controla tu ego. No puedes imponer a todo el mundo trabajar como te gusta. Porque se trata de eso: tu gusto.
• No confundir lo anterior con normas de codificación. Si el proyecto o la empresa (o el cliente), tiene unas normas de codificación, hay que seguirlas. Peor que ver código mal hecho, es ver código hecho de dos formas distintas en función de miembros del equipo disciplinados, y los "libres y ajenos a toda norma".
• las normas de codificación, y sobre todo, las relativas a los comentarios, han de ser muy simples. Un comentario no es tan importante como para perder tiempo con 200 páginas de normas y un curso intensivo de 3 días.
• El comentario no nos va a dar de comer: el código sí. Dicho esto, no significa que debamos ignorar y eliminar los comentarios. Si cada palabra clave o sintaxis del lenguaje que no nos gusta o "nos parece" poco útil se eliminara, os aseguro que entre unos y otros, sólo dejaríamos en el código líneas en blanco.
• Todos dejamos código basura. (unos más que otros,es cierto). Pues también hay comentarios basura. Y contra ambos hay que luchar.
• En tu empresa, en tu proyecto, adopta una forma de comentar simple y efectiva, minimalista. Usa sólo lo imprescindible y haz que todos lo adopten. Si trabajas solo, ten en cuenta que tu código o lo pueden usar en otros proyectos, o ya se está integrando en otros proyectos. Recuerda: hazte respetar respetando tú antes la forma de trabajo de los demás.

¿Estáis de acuerdo? ¿O sois defensores de los comentarios? ¿O abogáis por su más absoluta erradicación?
Por cierto, habrá que acuñar el término "Genocida de Comentarios", si esto llegara a ocurrir ;)
Y bueno, creo que ya vale para una entrada un tanto improvisada.
Un saludo a todos.