Guía para principiantes para escribir comentarios?

27

¿Existe una guía definitiva para escribir comentarios de código, dirigida a desarrolladores incipientes?

Idealmente, cubriría cuándo deberían (y no deberían) usarse los comentarios, y qué comentarios deberían contener.

Esta respuesta :

No comente QUÉ está haciendo, sino POR QUÉ lo está haciendo.

El QUÉ se soluciona mediante un código limpio, legible y simple con la elección adecuada de nombres de variables para admitirlo. Los comentarios muestran una estructura de nivel superior al código que no puede ser (o es difícil de mostrar) por el código mismo.

se acerca, pero es un poco conciso para programadores inexpertos (creo que una expansión con varios ejemplos y casos de esquina sería excelente).

Actualización : además de las respuestas aquí, creo que esta respuesta a otra pregunta es muy relevante.

language-agnostic comments Cameron
fuente
Creo que nos estamos mudando rápidamente a un mundo donde la gente ya no hace comentarios. Para mejor de (más probable) para peor. Ágil.
MK01
1
@MK: Si ese es el caso (tiendo a estar más de acuerdo con esta respuesta ), una guía que explique cómo no escribir comentarios y por qué deberían evitarse sería igualmente útil. De hecho, cuantos más puntos de vista diferentes, mejor.
Cameron
Creo que los pequeños comentarios para mejorar la velocidad de lectura de códigos son muy útiles y siempre lo serán. No compro completamente el razonamiento de "comentario obsoleto", incluso si son obsoletos, tendrían un valor histórico. Solía ​​trabajar en una base de código que ocasionalmente tenía comentarios detallados aquí y allá y nunca me mordió realmente porque el comentario no estaba actualizado.
MK01
ver también: "Los comentarios son un olor a código"
mosquito

Respuestas:

38

Debe tener en cuenta la mayor debilidad de los comentarios: se vuelven obsoletos. Es decir, a medida que el código cambia, los desarrolladores rara vez actualizan los comentarios para mantenerse sincronizados con el código. Esto significa que nunca puedes confiar en ellos y aún así terminar leyendo el código. Por esta misma razón, su código debe ser autodocumentado. Debe elegir su función y nombres de variables de tal manera que el código se lea como prosa.

Así que no documente QUÉ está haciendo el código. El código autodocumentado debería ocuparse de eso. Documente POR QUÉ lo está haciendo. Los POR QUÉ generalmente están relacionados con las reglas de negocios o la arquitectura y no cambian con frecuencia y se quedan obsoletos tan rápido en los QUÉ. Documentar casos de borde. Documentar excepciones. Documento de decisiones de diseño. Y lo más importante es documentar esas decisiones de diseño que consideró, pero decidió no implementar (y documente POR QUÉ decidió no usarlas).


fuente
2
El último es muy importante. A veces hay un error / efecto secundario al implementar la solución obvia. Documentar por qué eligió optar por alguna otra solución evita que el próximo desarrollador reintroduzca el error cuando "repara" una solución aparentemente pobre.
CaffGeek
2
Otro punto, mi primer trabajo consideró los comentarios tan importantes como el código. Intente acostumbrarse a leer comentarios y el código cuando realice una revisión por pares, e insista en que los comentarios estén actualizados siempre que sea posible. Esto ayuda a evitar que los comentarios se vuelvan obsoletos y mantiene las reglas comerciales, etc. documentadas en su código actualizadas.
Eric Hydrick
10

Deberías leer el libro Clean Code de Robert C. Martin . Explica muy bien que si necesita comentarios, lo más probable es que no esté codificando correctamente. Idealmente, su código debería ser "auto comentado". El libro Clean Coder explica cómo hacer esto, para que los comentarios no sean necesarios, y describe bien cómo hacer comentarios en situaciones donde es necesario. (Como explicar una fórmula matemática compleja)

Mover
fuente
Aunque no quisiera que se explicara una fórmula matemática compleja , me gustaría escribirla en una notación matemática adecuada (posiblemente TeX), con una explicación de su significado y fuente. Si no comprende la fórmula, entonces no debería meterse con el código que lo usa para calcular algún valor de todos modos, ya que es muy probable que arruine e introduzca errores (sutiles o no).
un CVn
El código solo puede decir cómo , no por qué o por qué no . Necesitas comentarios para eso.
7

Code Complete, como se mencionó, tiene varias pautas para escribir comentarios. En resumen, es PDL y se puede resumir como:

  1. Describa su intención, no lo que está haciendo el código. Evite describir detalles de implementación a menos que esté utilizando algún truco o esté utilizando implementaciones personalizadas. Por ejemplo, usar bits de desplazamiento para dividir, usar aritmética de puntero para acceder a miembros de la clase o usar un asignador de memoria personalizado para algunos objetos agrupados.

  2. Escriba el pseudocódigo (es decir, los comentarios) primero, luego escriba el código real una vez que haya terminado de describir su rutina / método / función. El lenguaje utilizado es de alto nivel pero específico, por lo que puede ser bastante detallado

  3. Tenga una idea de lo que está haciendo su código incluso antes de escribir el código

  4. Tener comentarios tan cercanos al código real

El objetivo es evitar comentarios no relacionados largos que pueden estar desactualizados, pero tener comentarios que reflejen la intención y el propósito del código. El uso de un pseudocódigo de alto nivel también ayuda a aclarar su pensamiento antes de escribir la implementación.

Hay un enlace en GameDev.net [que explica PDL] [1], en caso de que no quiera rastrear el libro.

Extrakun
fuente
55
Escriba el pseudocódigo (es decir, los comentarios) primero . No podría estar más en desacuerdo. No hay mejor manera de garantizar que los comentarios no coincidan con el código. Los nuevos codificadores (y el autor de la pregunta solicitó específicamente una guía para principiantes) piratearán y refactorizarán las funciones cientos de veces antes de que estén contentos con ellos, el código se moverá rápidamente, se reescribirá, se reubicará y, al final, podrán tienen una solución de trabajo elegante, pero no se parecerá en nada a su pseudo código inicial ¿Se moverán y actualizarán los comentarios a medida que el código funcione? Puedes apostar a tu dulce bippy que no lo harán. Mis dos centavos.
Binario Worrier
1
Además, los comentarios de pseudocódigo le dirán qué se supone que debe hacer el código. El código debería decirte eso. El pseudocódigo no le dirá por qué lo está haciendo el código. -1 amigo, lo siento, pero no puedo estar de acuerdo con el segundo punto, los tiempos han cambiado.
Binario Worrier
1
No para discutir, sino más para explicar: el pseudocódigo es para explicar la intención del código que ha escrito. Es decir, el comentario no se trata de detalles de implementación (como "Agregar x en la parte superior de la pila") sino de lo que se supone que debe hacer el código (como "Hacer que la ventana aparezca delante de todo lo demás"). Como ha señalado correctamente, debe mover los comentarios con el código. No estoy de acuerdo con el código, puedo decirte lo que está haciendo el código todo el tiempo. Incluso si un comentario útil / preciso (¡si logro escribirlo bien!) Es muy útil. Al final, aún en mi humilde opinión.
Extrakun
3
Un método o función llamada showWindowOnTop(window)siempre será mejor que un comentario de la misma naturaleza, todo esto está desactualizado y es un mal consejo en 2012. 1) Los nombres de función / método describen la intención, 2) el pseudocódigo es un ejercicio hueco con cadenas de herramientas modernas 3) Las pruebas le dicen lo que se supone que debe hacer el código antes de escribirlo, 4) el código bien nombrado es mejor que los comentarios que no coinciden con el código mal nombrado
1

Mi sugerencia sería escribir un código sin ningún comentario, y luego alejarme de él. Regrese en un año y léalo. La parte que no entiendes fácilmente es la parte que deberías haber comentado.

Kevin
fuente
1
Ja, sí ;-) Sin embargo, este no es un consejo particularmente útil, ¿tal vez esto debería haber sido un comentario?
Cameron
la parte que no comprende que debería haber escrito en partes más pequeñas y mejor nombradas. La razón principal por la que los comentarios se colocan en el código es que las funciones / métodos son demasiado largos y deben ser muchas piezas más pequeñas auto documentadas.
0

Realmente me gusta cómo Evan Todd resume su punto de vista sobre las únicas categorías de comentarios útiles ( citando de su blog ):

  • Comentarios que explican por qué, en lugar de qué. Estos son los más útiles.
  • Comentarios con algunas palabras que explican lo que hace el siguiente fragmento gigante de código. Estos son útiles para la navegación y la lectura.
  • Comentarios en la declaración de una estructura de datos, explicando qué significa cada campo. Estos a menudo son innecesarios, pero a veces no es posible asignar un concepto intuitivamente a la memoria, y los comentarios son necesarios para describir el mapeo.
Cameron
fuente