Aquí hay una pregunta que me gusta preguntarme al pensar si agregar un comentario en una sección del código: ¿Qué puedo transmitir que ayudaría a la siguiente persona a comprender mejor la intención del código? , ¿para que puedan actualizarlo, arreglarlo o extenderlo de manera más rápida y 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 usted ha escrito un código sólido de autodocumentación, 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 disminuir la pérdida de sincronización con el código real con el tiempo y, por lo tanto, hacer que sea 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 ya no serán evidentes en el código. Esto es bastante inevitable porque un buen programador siempre programa para el futuro, es decir, no solo para hacer que el programa funcione una sola vez, sino para hacer que todos sus muchos arreglos, versiones, extensiones y modificaciones en el futuro y los puertos y quién sabe qué también funciona correctamente. Este último conjunto de objetivos es mucho más difícil y requiere mucho más pensamiento para hacerlo bien. También es muy difícil expresarse bien en la mayoría de los lenguajes informáticos, que están más centrados en la funcionalidad, es decir, en lo que debe hacer esta versión del programa, ahora mismo, para poder 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á la complejidad suficiente como para que alguien que la busque por primera vez no reconozca de inmediato lo que es. Esa es una oportunidad para un buen comentario, porque puede agregar algo sobre el intento de su código que un lector posterior probablemente apreciará de inmediato como útil para descifrar los detalles.
A la inversa, en lenguajes como el Prólogo basado en la lógica, expresar la búsqueda de una pequeña lista puede ser tan trivial y sucinto que cualquier comentario cualquier que pueda agregar sería solo ruido. Entonces, un buen comentario es necesariamente dependiente del contexto. Esto incluye factores tales como las fortalezas del idioma 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 sobre cómo se debe entender y modificar el programa en el futuro. [1]
Para aquellas partes de su código que son realmente auto documentadas, los comentarios solo agregan ruido y aumentan el problema de coherencia para futuras versiones. Así que no los agregues allí.
Pero para aquellas partes de su código en las que 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 comentario. Un buen comentario en tal caso es uno que le permite a un programador futuro saber qué debe mantenerse igual, ese es el concepto de una afirmación invariable, incidentalmente, y qué está bien cambiar.
[1] Esto va más allá del tema de los comentarios, pero vale la pena comentarlo: si descubre que tiene una idea muy clara de cómo podría cambiar su código en el futuro, probablemente debería pensar más allá de solo hacer un comentario y incruste esos parámetros en el propio código, 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 persona desconocida en el futuro en la dirección correcta. Al mismo tiempo, también desea evitar el exceso de generalización, ya que los humanos son notoriamente malos para predecir el futuro, y eso incluye el futuro de los cambios en los programas. Por lo tanto, intente definir y capturar dimensiones de futuro razonables y bien probadas en todos los niveles de diseño del programa, pero no permita que lo distraiga en un ejercicio de generalización excesiva que es poco probable que se pague en el largo plazo. p>