Los comentarios siempre son incorrectos, ¿correcto o no?

Question

Al azar encontré este blog sobre cómo uno nunca debe leer los comentarios, y pensé en mí mismo todos los comentarios que he leído que fueron incorrectos, fechados o simplemente confusos. Debería uno simple nunca leer los comentarios y/o simplemente usar el patrón de regex replace para eliminar ... :-) ... es broma, pero realmente, tal vez no. Por lo menos parece como comentarios y el código relacionado debe tener timestamps. De acuerdo, o no?

FYI, el blog parece ser de este usuario stackoverflow: Nosredna

Answer 1

Un comentario inexacto es tan serio de un error como un código incorrecto. Si se trata de un problema persistente, diría que el proyecto tiene serios problemas. Los grandes proyectos como PostgreSQL (94M sin comprimir en el directorio src) se basan en comentarios precisos para ayudar a los programadores a entender las cosas rápidamente. También toman los comentarios muy en serio.

edición:

Además, si usted no puede resumir lo que su función está haciendo, entonces, ¿quién puede? Una vez que haya terminado de escribir una función, escribir el comentario puede ser una prueba de que comprende completamente lo que está sucediendo. Si las cosas todavía están un poco embarradas en tu mente, será muy evidente cuando intentes escribir el comentario. Y esto es algo bueno, que muestra lo que aún debe ser trabajado.

Answer 2

Algunos comentarios son útiles y buenos, otros comentarios no son.

Sí, los comentarios y el código deben tener una marca de tiempo, pero no debe marcarlo usted mismo. Su sistema de control de origen debe gestionar esto por usted, y debe poder acceder a esta información (por ejemplo, usando cvs annotate o svn blame).

Answer 3

Los comentarios de código a veces pueden ser invaluables. Muchas veces me he esforzado por determinar la intención del código sin éxito. Para el código de cualquier complejidad, puede ser útil si el autor documenta su intención. Por supuesto, las pruebas unitarias bien redactadas también pueden aclarar la intención.

Answer 4

En el mundo real, la programación no solo significa escribir código. Significa escribir código que otro programador (o usted mismo, en 3 meses) puede comprender y mantener de manera eficiente.

Cualquier programador que te dice que los comentarios y/o documentación no vale la pena el tiempo que se tarda en escribir/mantenerlas tiene una serie de problemas:

• Su ritmo de trabajo a largo plazo (y la de los compañeros que tiene que trabajar con su código) será menor de lo que podría ser. La gente perderá mucho tiempo entendiendo el código que podría describirse en una oración rápida.

• Las tasas de error relacionadas con su código serán más altas de lo que podrían ser, porque todas esas suposiciones y casos especiales que olvidó mencionar constantemente harán tropezar a la gente. (¿Cuántas veces ha tenido que hacer algo "inusual" en su código para hacer que algo funcione, olvidó comentarlo para decir por qué lo hizo de esa manera, y luego pensó que parecía un error y lo "arregló", sólo para descubrir que has roto cosas terriblemente debido a una sutileza que no recordabas?)

• Si él es demasiado flojo para anotar cómo funciona o debería usarse su código, ¿qué otros atajos está tomando? ¿Se molesta en buscar nulos y manejar excepciones? ¿Le importa que sus interfaces sean consistentes?¿Se molestará en refactorizar el nombre de un método/variable si su significado subyacente cambia? Por lo general, los malos comentarios son solo la punta del iceberg.

• Muchos de esos programadores están demasiado centrados en "las cosas interesantes" (como optimizar cada último ciclo de su código, o encontrar una manera ingeniosa de ocultar una pieza aparentemente simple en una plantilla desconcertante) para comprender las realidades comerciales (por ejemplo, puede tener problemas para que su código funcione y se envíe a plazos porque se centra en exprimir el rendimiento innecesario en lugar de simplemente hacer el trabajo)

• ¿Qué tan buenos son sus diseños? Hago la mayor parte de mi diseño y pensamiento cuando escribo documentos/comentarios. Al tratar de explicarle al lector mis comentarios, eliminé muchos errores y suposiciones que de otra forma me perdería. Me atrevería a decir que normalmente escribo comentarios (mi intención/diseño) y luego sincronizo el código con ellos. En la mayoría de los casos, si hay un error en mi código, es el código que es incorrecto no el comentario.

• No se ha dado cuenta de que al usar buenos nombres variables, prefijos de nombres bien diseñados/convenciones y comentarios de documentación, puede hacer un mejor uso de las fabulosas funciones de ahorro de tiempo de su IDE (autocompletar, ayuda intellisense, etc.) y codifica mucho más rápido, con tasas de defecto más bajas.

Fundamentalmente, es probable que no entiende cómo escribir buenos comentarios:

1) Comentarios debería actuar como una de lectura rápida Resumen de un trozo de código. Puedo leer una breve línea de texto en lugar de tener que descifrar el significado de muchas líneas de código. Si te encuentras leyendo el código para navegar por él, está poco comentado. Leí los comentarios para navegar y entender el código, y solo leo el código cuando realmente necesito trabajar en ese bit específico.

2) Los comentarios de Método/Clase deben describir a quien llama todo lo que necesitan saber para usar esa clase, sin tener que mirar dentro de la "caja negra" de la implementación del código. Podrán comprender rápidamente cómo usar la clase/método y comprender todos los efectos secundarios y el "contrato" que proporciona una API: qué puede ser nulo y qué se debe proporcionar, y qué excepciones se lanzarán, etc. Si tiene que leer el código para obtenerlo, está mal encapsulado o mal documentado.

3) Use herramientas como mi complemento AtomineerUtils o Submain's GhostDoc, lo que significa que sus comentarios sobre la documentación pueden mantenerse sincronizados con el código con muy poco esfuerzo.

Answer 5

Personalmente no escribo un montón de comentarios, pero los tipos más comunes de los comentarios que hago escritura son:

• (croquis) pruebas de que mi código es correcto
• explicaciones de por qué no acaba de hacer lo obvio (e.g: se requirió optimización, la API que estoy llamando es sorprendentemente engañosa, la "cosa obvia" condujo a una falla sutil)
• una descripción de la entrada de borde-caja que requiere un manejo especial, lo que explica por qué el código de manejo especial aparece
• una referencia al requisito o especificación que exige el comportamiento implementado por una línea de código particular
• descripción de nivel superior de una serie de pasos realizados: ("primero obtener la entrada", "ahora quitar la envoltura" , "finalmente analizarlo"), que no son necesarios si los nombres de las funciones solicitadas para cada paso están bien elegidos y no tienen ambigüedad en el contexto, pero no voy a escribir un contenedor de do-nothing para una función genérica solo para darle un nombre más específico para un solo uso
• documentación que se extraerá automáticamente. Esta es una gran proporción de comentarios por volumen, pero no estoy seguro de que "realmente cuente".
• cosas que podrían ser ser parte de la interfaz documentada, pero no es porque necesiten cambiar en el futuro, o porque son elementos internos que los externos no necesitan. Por lo tanto, es útil para el implementador tener en cuenta, pero no para el usuario. Las invariantes de clases privadas se incluyen en esto: ¿realmente desea leer toda la clase cada vez que quiera confiar en "este miembro no es nulo", o "el tamaño no es mayor que la capacidad" o "acceso a este miembro"? debe estar sincronizado "? Es mejor verificar la descripción del miembro antes de asignarlo, para ver si está autorizado. Si alguien no tiene la disciplina para evitar romper un invariante claramente comentado, bueno, no es de extrañar que todos sus comentarios sean incorrectos ...

Algunas de estas cosas se manejan mediante pruebas exhaustivas, en el sentido de que si las pruebas pasan y el código es correcto (hah), si tienes el código de prueba abierto también puedes ver los casos de entrada especiales, y si algún tonto oculta los comentarios, comete el mismo error que yo originalmente y vuelve a generar mi código para hacer lo obvio, entonces las pruebas fallarán. Eso no significa que los comentarios no lo manejen mejor, en el contexto de la lectura a través del código. En ninguno de estos casos, leer el comentario es un sustituto para leer el código, están diseñados para resaltar lo que es importante pero no obvio.

Por supuesto, en el caso de los documentos automáticos, es perfectamente razonable, y probablemente más útil, ver la documentación por separado.

Al depurar, en lugar de realizar cambios, es manera más valioso para que el código se explique. Los comentarios son menos útiles, especialmente las invariantes privadas, porque si estás depurando, hay una posibilidad razonable de que quien escribió el código + comentarios cometió un error, por lo que los comentarios pueden ser incorrectos. En el lado positivo, si ve un comentario que no refleja lo que hace el código, hay una posibilidad razonable de que haya encontrado un error. Si solo ves lo que hace el código, puede pasar un tiempo antes de que te des cuenta de que lo que hace el código no es lo que se supone que debe hacer.

A veces un buen nombre ayuda mucho a reemplazar los comentarios. Sin embargo, los nombres pueden ser tan engañosos como los comentarios si son incorrectos. Y, seamos sinceros, con frecuencia los nombres son al menos ligeramente engañosos o ambiguos. Dudo que el autor de esa publicación en el blog llegue al extremo de reemplazar todos los nombres con "var1, var2, func1, func2, class1, class2 ...", solo para asegurarse de que no estén distraídos por el autor original. intenciones incorrectas para el código. Y no creo que sea más cierto decir que "los comentarios siempre son incorrectos" que decir que "los nombres de variables siempre son incorrectos". Están escritos por la misma persona al mismo tiempo con el mismo propósito.

Answer 6

Comentario por qué está haciendo algo y no lo que hizo sintácticamente.