La mezcla entre un código bien escrito junto al uso de comentarios, colaboran a que el lector pueda comprender de mejor manera el propósito de este. Por lo cual, he decidido crear este aporte que incluye estas cuatro reglas sugeridas por el co-fundador de Stack Overflow, Jeff Atwood, también conocido cómo «Coding Horror»:
Los buenos comentarios son los que se mantienen lo más cerca posible del código al que hacen referencia. Es decir, los comentarios que no están cerca de su código de descripción son frustrantes para el lector y se pierden fácilmente cuando se realizan actualizaciones.
No utilices formatos complejos (como tablas o figuras ASCII). El formato complejo es una molestia para editar y genera desmotivación para el mantenimiento: Pongámonos en el caso de que si ya es difícil editar un comentario, es muy probable que un desarrollador evite siquiera el esfuerzo de contribuir al, valga la redundancia, desarrollo de este.
No incluya información redundante, sea preciso y directo con lo que quiere comentar. Colóquese en el caso de que el lector tenga poca experiencia dentro del lenguaje usado. Además, el hecho de que sea redundante reduce la posibilidad de que quien edite el código recuerde cada edición de ese comentario ambiguo.
El mejor comentario es el cuerpo de tu código, si nosotros diseñamos un código legible este podrá ser comentado de la mejor manera. Por lo tanto, la forma más sencilla de entender el código es comentando un código bien escrito; así aseguramos que tanto lectores como desarrolladores puedan comprender y contribuir al desarrollo del proyecto.
