Aquí hay una pregunta que me gustaría hacerme al pensar si agregar un comentario en una sección de código: ¿Qué puedo transmitir que ayude a la siguiente persona a comprender mejor la intención general del código, para que pueda actualizar, corregir o extenderlo más rápido y de manera más confiable?
A veces, la respuesta correcta a esta pregunta es que no hay mucho que pueda agregar en ese punto del código, porque ya ha seleccionado nombres y convenciones que hacen que la intención sea lo más obvia posible. Eso significa que ha escrito un código autodocumentado sólido, y que insertar un comentario allí probablemente restaría más de lo que ayudaría. (Tenga en cuenta que los comentarios redundantes en realidad pueden dañar la confiabilidad del código con el tiempo al desacelerar la caída de la sincronización con el código real con el tiempo y, por lo tanto, es más difícil descifrar la intención real.
Sin embargo, en casi cualquier programa y en cualquier lenguaje de programación, encontrará puntos en los que ciertos conceptos críticos y decisiones tomadas por el programador original, por usted, ya no serán aparentes en el código. Esto es casi inevitable porque un buen programador siempre programa para el futuro, es decir, no solo para hacer que el programa funcione una vez, sino para hacer todas sus correcciones y versiones y extensiones y modificaciones y puertos futuros y quién sabe qué hacer. También funciona correctamente. Ese último conjunto de objetivos es mucho más difícil y requiere mucha más reflexión para hacerlo bien. También es muy difícil expresarse bien en la mayoría de los lenguajes de computadora, que están más enfocados en la funcionalidad, es decir, en decir qué hace esto versión del programa debe hacer, ahora mismo, para que sea satisfactorio.
Aquí hay un ejemplo simple de lo que quiero decir. En la mayoría de los idiomas, una búsqueda rápida en línea de una pequeña estructura de datos tendrá suficiente complejidad como para que alguien que la vea por primera vez no reconozca de inmediato de qué se trata. Esa es una oportunidad para un buen comentario, porque puede agregar algo sobre la intención de su código que un lector posterior probablemente apreciará de inmediato como útil para descifrar los detalles.
Por el contrario, en idiomas como el lenguaje Prolog basado en la lógica, expresar la búsqueda de una pequeña lista puede ser tan increíblemente trivial y sucinto que cualquier comentario que pueda agregar sería solo ruido. Por lo tanto, un buen comentario depende necesariamente del contexto. Eso incluye factores como las fortalezas del lenguaje que está utilizando y el contexto general del programa.
La conclusión es esta: piensa en el futuro. Pregúntese qué es importante y obvio para usted acerca de cómo debe entenderse y modificarse el programa en el futuro. [1]
Para aquellas partes de su código que realmente se documentan por sí mismas, los comentarios solo agregan ruido y aumentan el problema de coherencia para futuras versiones. Entonces no los agregue allí.
Pero para aquellas partes de su código donde tomó una decisión crítica de varias opciones, o donde el código en sí es lo suficientemente complejo como para que su propósito sea oscuro, agregue su conocimiento especial en forma de un comentario. Un buen comentario en tal caso es uno que le permite a algún futuro programador saber qué debe mantenerse igual, ese es el concepto de una afirmación invariable, por cierto, y qué está bien cambiar.
[1] Esto va más allá del tema de los comentarios, pero vale la pena mencionarlo: si descubres que tienes una idea muy clara de cómo podría cambiar tu código en el futuro, probablemente deberías pensar más allá de solo hacer un comentario e incrustar esos parámetros dentro del código en sí mismo, ya que casi siempre será una forma más confiable de garantizar la confiabilidad de futuras versiones de su código que tratar de usar comentarios para dirigir a una futura persona desconocida en la dirección correcta. Al mismo tiempo, también desea evitar la generalización excesiva, ya que los humanos son notoriamente malos para predecir el futuro, y eso incluye el futuro de los cambios del programa. Por lo tanto, trate de definir y capturar dimensiones razonables y probadas del futuro en todos los niveles del diseño del programa, pero no lo haga.