¿Los comentarios se consideran una forma de documentación?

Cuando escribo pequeños scripts para mí, apilo mi código con comentarios (a veces comento más de lo que codifico). Muchas personas con las que hablo dicen que debería documentar estos guiones, aunque sean personales, de modo que si alguna vez los vendo, estaría listo. ¿Pero no son los comentarios una forma de documentación?

¿No sería esto?

$foo = "bar"; # this is a comment
print $foo; # this prints "bar"

ser considerado documentación, especialmente si un desarrollador está usando mi código? ¿O se considera que la documentación está fuera del código mismo?

Los comentarios son definitivamente documentación. Para la mayoría de los proyectos, los comentarios son (desafortunadamente) la forma principal (si no solo) de documentación del proyecto. Por esta razón, es muy importante hacerlo bien. Debe asegurarse de que esta documentación se mantenga precisa a pesar de los cambios en el código. Este es un problema común con los comentarios. Los desarrolladores a menudo los "desconectan" cuando trabajan en un código familiar, por lo que se olvidan de actualizar los comentarios para reflejar el código. Esto puede crear comentarios desactualizados y engañosos.

Mucha gente sugiere hacer que el código se documente automáticamente. Esto significa que en lugar de comentarios, reestructura su código para eliminar la necesidad de ellos. Esto puede eliminar la mayoría de los comentarios de "qué" y "cómo", pero en realidad no ayuda con los comentarios de "por qué". Si bien esto podría funcionar de manera efectiva para deshacerse de la mayoría de los comentarios, todavía hay muchas veces en que escribir un comentario es la forma más simple y eficiente de documentar un fragmento de código.

Son una forma de documentación, pero recuerde que la documentación está en el ojo del espectador ...

• Para algunos, el código autodocumentado es suficiente. Pero eso supone un nivel de detalle técnico como el cliente. Debemos tener cuidado al pensar que esto es suficiente, porque nuestro ego puede decirnos "Es obvio lo que está haciendo este código" pero el tiempo puede demostrar lo contrario. También supone que conoce de antemano las habilidades del lector.

• Para aquellos que buscan el código fuente pero con menos experiencia técnica, los comentarios podrían estar bien. Pero eso supone que alguien está mirando el código fuente.

• Si es técnico, pero le falta tiempo para leer todo el código fuente, un manual técnico podría ser lo que se requiere.

• Si el usuario carece de habilidades técnicas, pero solo necesita saber qué está sucediendo, la documentación del usuario es lo que se necesita.

Entonces, la verdadera pregunta es ¿quién es su cliente? Si es así, entonces es suficiente documentar el código o los comentarios. Si es para otra persona, es posible que desee ampliar la forma en que documenta.

Sí, los comentarios son una forma de documentación. Si son o no documentación útil para alguien que tiene que mantener o actualizar su código es una pregunta abierta.

Sé que lo dijiste como un ejemplo de usar y tirar, pero cosas como

print $foo; # this prints "bar"

no es útil solo agrega desorden visual. No documentar lo obvio.

Los comentarios de bloque en la cabecera de un método o definición de función que describen el propósito de la función o método (en términos de alto nivel ), entradas, salidas, valor de retorno (si lo hay), excepciones (si las hay), condiciones previas y condiciones posteriores son útiles, pero solo en la medida en que le digan a alguien cómo se supone que se debe usar la función o el método. No explican por qué existe la función.

Si alguien más necesita mantener su código, entonces necesita documentar los requisitos y el diseño en algún lugar, y eso generalmente no se hace en el código fuente en sí.

Creo que apegarse al enfoque de Bob Martin sobre esto, desde Clean Code, generalmente resuelve el problema de si crees que estás comentando demasiado o no estás comentando y dejando de lado la documentación:

Somos autores Y una cosa sobre los autores es que tienen lectores. De hecho, los autores son responsables de comunicarse bien con sus lectores. La próxima vez que escriba una línea de código, recuerde que es un autor y escribe para lectores que juzgarán su esfuerzo.

... la proporción de tiempo dedicado a leer frente a escribir es muy superior a 10: 1. Estamos constantemente leyendo el código antiguo como parte del esfuerzo para escribir código nuevo.

En otras palabras, ¿su código se explica por sí mismo sin la documentación? No hay una regla establecida para ello (a menos que trabaje para alguien como Microsoft cuya documentación sea de acceso público), se debe principalmente a ayudar al futuro lector del código, que a menudo es usted.

La documentación debe documentar el por qué no el cómo . El Cómo debería ser evidente en el código, es decir, a menos que sea un truco de optimización arcano u otra técnica específica del lenguaje que no ocurre comúnmente.

El por qué probablemente no debería estar en el código, debería estar en otro lugar, como el trabajo atrasado de un producto, que está vinculado para confirmar comentarios con identificadores de historias que se pueden buscar en un registro de cambios o nombre de sucursal.

Los comentarios son una forma de documentación. Una forma inferior, y una que sugiere que ha localizado un área de su código que se puede factorizar mejor.

Parece que comentas cosas compulsivamente. Tener otras opciones puede ser algo bueno. Puedo pensar en tres formas superiores de documentación:

1) Factoriza mejor tu código. En lugar de agregar un comentario, extraiga un método o función cuyo nombre sea el texto del comentario que estaba a punto de escribir. Entonces el código dice lo que tu comentario estaba por decir.

2) Pruebas. Esta es la forma de documentación que generalmente busco. Las pruebas unitarias y las pruebas de aceptación son documentación viva y pueden leerse fácilmente si se utilizan muchos métodos significativos para expresar la intención, como en el punto 1.

3) Para los scripts, la opción --help. Aquí es donde puedes volverte loco con el doc. Pegue ejemplos, anticipe lo que el usuario necesitaría.

En resumen, si se encuentra inclinado a escribir un comentario, verifique si hay una manera de comunicarse con el lector estructurando mejor el código. ¿O hay una prueba que comunica por qué ese código está ahí? Si todavía te sientes inclinado a comentarlo, admite la derrota y hazlo.