Mejores prácticas para escribir comentarios de código

El famoso profesor del MIT Hal Abelson ha dicho: «Los programas deben estar escritos para que la gente los lea y solo de manera incidental para que los ejecuten las máquinas». Si bien puede haber subestimado deliberadamente la importancia de ejecutar código, está en lo cierto en que los programas tienen dos audiencias muy diferentes. Los compiladores e intérpretes ignoran los comentarios y encuentran que todos los programas sintácticamente correctos son igualmente fáciles de entender. Los lectores humanos son muy diferentes. Encontramos algunos programas más difíciles de entender que otros, y buscamos comentarios para ayudarnos a entenderlos.

While there are many resources to help programmers write better code—such as books and static analyzers—there are few for writing better comments. While it’s easy to measure the quantity of comments in a program, it’s hard to measure the quality, and the two are not necessarily correlated. A bad comment is worse than no comment at all. As Peter Vogel has written:

  1. Escribir y luego mantener comentarios es un gasto.
  2. Su compilador no revisa sus comentarios, por lo que no hay forma de determinar que los comentarios sean correctos.
  3. Por otro lado, tiene la garantía de que la computadora está haciendo exactamente lo que su código le dice.

Si bien todos estos puntos son ciertos, sería un error ir al otro extremo y nunca escribir comentarios. Aquí hay algunas reglas que le ayudarán a alcanzar un punto medio feliz:

  • Regla 1: Los comentarios no deben duplicar el código.
  • Regla 2: Los buenos comentarios no excusan el código poco claro.
  • Regla 3: si no puede escribir un comentario claro, es posible que haya un problema con el código.
  • Regla 4: Los comentarios deben disipar la confusión, no causarla.
  • Regla 5: Explique el código unidiomático en los comentarios.
  • Regla 6: Proporcione enlaces a la fuente original del código copiado.
  • Regla 7: Incluya enlaces a referencias externas donde sean más útiles.
  • Regla 8: agregue comentarios al corregir errores.
  • Regla 9: Utilice comentarios para marcar implementaciones incompletas.

Publicaciones Similares

¿Qué es React?

ReactJS no es un framework en sí mismo sino una biblioteca JavaScript de código abierto desarrollada por Facebook. Su principal función es la de estar diseñada para facilitar la creación de interfaces de usuario de una manera ágil y versátil. Tanto que hace palidecer a frameworks, sí frameworks, como AngularJS, del cual es…

|

¿Qué es UI?

Qué es el Diseño de Interfaces (UI) El Diseño de Interfaz o User Interface (UI), se refiere a todo aquello con lo que los usuarios interactúan directamente (la capa externa de un producto o servicio digital). Es lo que ve y toca en una página web, una aplicación o un dispositivo cualquiera….