¿cómo se debe comentar un código?

Comentarios divertidos en el código

En programación informática, un comentario es una explicación o anotación legible para el programador en el código fuente de un programa informático. Se añaden con el fin de facilitar la comprensión del código fuente por parte de los humanos, y generalmente son ignorados por los compiladores e intérpretes[1][2] La sintaxis de los comentarios en los distintos lenguajes de programación varía considerablemente.

A veces, los generadores de documentación procesan los comentarios de diversas maneras para generar documentación externa al propio código fuente, o los utilizan para la integración con sistemas de gestión de código fuente y otros tipos de herramientas de programación externas.

Los comentarios en bloque delimitan una región del código fuente que puede abarcar varias líneas o una parte de una sola línea. Esta región se especifica con un delimitador inicial y otro final. Algunos lenguajes de programación (como MATLAB) permiten que los comentarios de bloque se aniden recursivamente unos dentro de otros, pero otros (como Java) no lo permiten[4][5][6].

Los comentarios de línea comienzan con un delimitador de comentario y continúan hasta el final de la línea, o en algunos casos, comienzan en una columna específica (desplazamiento de línea de caracteres) en el código fuente, y continúan hasta el final de la línea[6].

Ejemplos de comentarios de código

El famoso profesor del MIT Hal Abelson ha dicho: “Los programas deben escribirse para que la gente los lea y sólo incidentalmente para que las máquinas los ejecuten”. Aunque es posible que haya subestimado a propósito la importancia de la ejecución del código, tiene razón en que los programas tienen dos públicos muy diferentes. Los compiladores e intérpretes ignoran los comentarios y consideran que todos los programas sintácticamente correctos son igualmente fáciles de entender. Los lectores humanos son muy diferentes. Algunos programas nos resultan más difíciles de entender que otros, y recurrimos a los comentarios para que nos ayuden a entenderlos.

Aunque hay muchos recursos para ayudar a los programadores a escribir mejor código -como libros y analizadores estáticos-, hay pocos para escribir mejores comentarios. Aunque es fácil medir la cantidad de comentarios en un programa, es difícil medir la calidad, y ambas cosas no están necesariamente correlacionadas. Un mal comentario es peor que no tener ningún comentario. Como ha escrito Peter Vogel

Muchos programadores noveles escriben demasiados comentarios porque fueron entrenados para ello por sus instructores de introducción. He visto a estudiantes de clases de informática de nivel superior añadir un comentario a cada llave cerrada para indicar qué bloque está terminando:

¿debes comentar el código?

Básicamente para resumir, eres un mal programador si no escribes comentarios. Mi opinión personal es que el código debe ser descriptivo y en su mayoría no requiere comentarios a menos que el código no pueda ser autodescriptivo.

Esto, por supuesto, no significa que uno nunca deba usar comentarios – tienen su papel, pero IMHO debe usarlos con cuidado. Esta respuesta anterior mía en SO explica mis pensamientos sobre el tema con más detalle.

Por supuesto, como señaló @Niphra, siempre vale la pena volver a comprobar que lo que creo que es limpio es realmente comprensible para los demás. Sin embargo, esto también es una cuestión de práctica. Ya en la uni escribí piezas de código crípticas simplemente por usar nombres extraños y divertidos para todas las entidades del código, según mi capricho. Hasta que mi profesor me devolvió uno de mis trabajos, señalando amablemente que no podía averiguar qué módulo era el principal 🙂 Fue una buena lección, así que desde entonces me esforcé en escribir un código cada vez más legible. Hoy en día apenas recibo quejas de mis compañeros de equipo.

En realidad, no creo en el código autodescriptivo. Hay código más legible y menos legible, dependiendo del lenguaje, de tu conocimiento del mismo (como autor original), del conocimiento del que lo lee y de la función del código. Pero no, aún así… debería describirse con un breve comentario.

Comentario del código

Resuma de qué trata el código. Puede ser obvio cuando lo escribes, pero no dos años después, así que escribe cuándo se usa este código en la aplicación, por qué se usa y demás. Por ejemplo, “este código gestiona la situación en la que un usuario rellena un formulario quejándose de paquetes devueltos perdidos en el correo”. Responde a la pregunta “para qué demonios sirve este código”.

Comentarios en los archivos de cabecera (o en lugares donde se extraen automáticamente) para que, para cada función pública, un lector sepa qué hace y por qué debe llamarse sin tener que consultar el código fuente.

Especialmente para las funciones virtuales: Comentarios en los archivos de cabecera sobre lo que se supone que hace esta función, incluyendo los overrides. En el caso de las funciones no virtuales, los comentarios son una comodidad que me ahorra leer el código fuente. Para las funciones virtuales, no hay código fuente.

Comentarios que indican a otros desarrolladores cuando se hace algo que parece raro. Hay lugares en los que mi código contiene algunas líneas que parecen una absoluta tontería, y luego hay un comentario “Funciona alrededor de un error en la biblioteca XYZ”.