- ¿Por qué no comentarios de "por qué no"? No por qué "no comentarios"
- “¿Por qué no dejan comentarios sobre ‘por qué no funcionó’? No estoy preguntando por qué ‘no dejaron comentarios’.”
Por qué no comentarios
- El código se escribe en un lenguaje de máquina estructurado, y los comentarios se escriben en un lenguaje humano rico en expresividad
- Significa que no hay que comentar el "qué", sino incluir tanta información como sea posible en los identificadores
- Últimamente también se ha argumentado que ni siquiera el "por qué" debería ir en comentarios, sino en
LongFunctionNames o en nombres de casos de prueba
- Un codebase "autodocumentado" agrega documentación a través de los identificadores
Ejemplo reciente
- Un ejemplo de
Logic for Programmers
- Surgió un problema en el que la compilación epub no podía convertir símbolos matemáticos (
\forall) en caracteres (∀)
- Se escribió un script para reemplazar manualmente los tokens de cadenas matemáticas por Unicode
- Se implementó reemplazando por separado 16 símbolos matemáticos, pero eso es ineficiente
- Se resolvió fácilmente agregando un comentario
- "Repite 16 veces para cada cadena, pero por ahora el libro solo tiene 25 cadenas matemáticas y la mayoría tiene menos de 5 caracteres, así que sigue siendo lo bastante rápido"
Por qué hay que comentar
- La razón para agregar comentarios incluso cuando el código lento no causa problemas
- En el futuro, el código podría convertirse en un problema
- Los comentarios muestran que uno es consciente de los trade-offs
- Cuando vuelvas a ver el proyecto más adelante, podrás entender por qué escribiste código lento
Por qué la autodocumentación es imposible
- Nombres de función largos como
RunFewerTimesSlowerAndSimplerAlgorithmAfterConsideringTradeOffs no explican los trade-offs
- Los identificadores de funciones y variables solo pueden contener una pieza de información
- Tampoco es posible reemplazar los comentarios con tests
- La autodocumentación explica lo que hace el código, pero la información negativa explica lo que el código no hace
Especulación al final del boletín
- Se pregunta si los comentarios de "por qué no" pueden pensarse como casos contrafácticos
- ¿La abstracción de la comunicación humana hace imposible la autodocumentación?
- ¿Se pueden autodocumentar metáforas, incertidumbre, afirmaciones éticas y similares?
Resumen de GN⁺
- Este texto trata sobre la importancia de los comentarios en el código y sus límites
- Los comentarios ayudan a aclarar los trade-offs del código y facilitan el mantenimiento futuro
- Se enfatizan los límites de la autodocumentación y la necesidad de los comentarios
1 comentarios
Opiniones de Hacker News
Al poner comentarios en el código, se debe explicar principalmente el "por qué" y el "por qué no". Si el código es complejo, también es útil explicar brevemente el "qué"
Los ingenieros junior escriben comentarios que explican qué hace el código, los de nivel intermedio explican por qué se escribió así, y los senior explican por qué no se escribió de otra manera
Se usa una plantilla de comentarios para quienes den mantenimiento
Es importante comentar las partes sorprendentes del código
Se enfatiza la importancia de los comentarios, especialmente cuando uno mismo tendrá que dar mantenimiento a su código dentro de 5, 10 o 15 años
Es bueno comentar lo que "no es la solución ingenua"
Es buena idea incluir comentarios en nombres largos de funciones o de casos de prueba
También es útil agregar advertencias mediante debug logging cuando la entrada supera las restricciones de diseño originales
Se prefiere usar muchos comentarios y comentarios de documentación
En las revisiones de código, se escriben comentarios como "La razón por la que no hice X es Y" para prevenir de antemano críticas esperadas