---

Esta es una compilación de varias ideas, buenas prácticas y algunos principios en los que se sustentan. No es la intención hacer un análisis o crear una metodología al respecto. A lo más se trata de un ejercicio personal en el que a la experiencia práctica se contrasta con lo publicado por otros al respcto buscando crear un estilo personal.

El contenido de esta página debe considerarse como «en construcción» hasta que retire este comentario… 🙂

Las reglas

1. Los comentarios no deben duplicar el código, pero por ausencia de éstos, el propósito detrás de las acciones codificadas no puede ser obscuro.
2. Los buenos comentarios no deben substituir o complementar lo que el código mismo podría decir.
3. Si no se puede escribir un comentario claro, es que la intención del código tampoco lo es.
4. Los comentarios deben dar información y no crear incertidumbre.
5. Las intenciones deben ser explicadas, no las particularidades de un lenguaje de programación.
6. El código, así como las citas en un texto, debe ser apropiadamente atribuido, incluyendo aquello que no necesariamente sea código.
7. Agregue comentarios al corregir errores.
8. Use comentarios para marcar implementaciones incompletas.

Estilos

La mayoría de los lenguajes de programación proveen la forma de incluir comentarios en línea y por bloque. Para ambas modalidades hay recomendaciones sobre la posición y adornado a seguir. En particular, para los comentarios de bloque, el adornado debe:

• permitir destacar la líneas que componen el comentario, pero
• no deben sobrecargar visualmente la percepción del código.

Por ejemplo, para un lenguaje de scripting de un shell unix, un posible esquema de documentación podría ser:

#!

#
# script.sh v0.0.0
#
# Descripción del propósito del script.
# 
# Descripción de entradas
#
# Descripción de salida o resultado
#
# Autor
#==============================================================

#
# Descripción de funciones
#
 
# Descripción del propósito de instrucciones

############################# END #############################

# Historial de versiones y revisiones
#

# v0.0.0 Fecha
# Texto 

Referencias

1. Ellen Spertus, «Best practices for writing code comments«, stackoverflow.blog, blog. Published: 2021.12.31; visited: 2022.05.31. URL: https://stackoverflow.blog/2021/12/23/best-practices-for-writing-code-comments/.
2. Michiel Mulders, «The Engineer’s Guide to Writing Meaningful Code Comments», stepsize.com, blog. Published: 2021.06.14, visited: 2023.04.02. URL: https://www.stepsize.com/blog/the-engineers-guide-to-writing-code-comments.
3. Elena Kosourova, «The Art of Writing Efficient Code Comments«, towardsdatascience.com, blog. Published: 2021.04.22, visited: 2023.04.02. URL: https://towardsdatascience.com/the-art-of-writing-efficient-code-comments-692213ed71b1.

---

	© Todos los derechos reservados. Dr. Eduardo René Rodríguez Avila	Creación: 2022.05.31 Última actualización: 2023.04.02
El contenido de este sitio puede ser copiado y reproducido libremente mientras no sea alterado y se cite su origen. Marcas y productos registrados son citados por referencia y sin fines de lucro o dolo. Todas las opiniones son a título personal del o los autores de éstas y, salvo sea expresado de otro modo, deben considerarse como registro y expresión de la experiencia de uso de aquello que es tratado. Para conocer más sobre la posición de privacidad y responsabilidad de lo que se presenta en este sitio web y como ha sido obtenido, consulte la declaración al respecto.