¿Forzar a las personas a leer y entender el código en lugar de usar comentarios, resúmenes de funciones y depuradores? [duplicar]

El código bien escrito debe ser lo suficientemente autodocumentado para que no necesite ningún comentario que explique lo que hace el código, porque es obvio al leer el código en sí. Esto implica también que todas las funciones y variables tienen nombres descriptivos, aunque podría ser necesario para aprender la jerga del problema y los dominios de solución.

Esto no significa que el código bien escrito deba estar completamente sin comentarios, porque los comentarios importantes son aquellos que explican por qué se implementa una función / bloque / etc particular, no trivial, tal como está y por qué no se ha elegido una solución diferente.

El problema con los comentarios que describen el código en sí es que tienden a estar desactualizados, porque el código se modifica para corregir un error, pero los comentarios permanecen intactos. Este es mucho menos el caso de los comentarios que describen el razonamiento para llegar a la solución actual.

Alguien (atribuido a Richard C. Haven , un programador de Delphi) escribió una vez:

• Los principiantes no comentan nada.

• Los hombres del viaje comentan lo obvio.

  myVar = myVar + 1; // add one to myVar
  
  /* This method adjusts the page margin by the appropriate device offset */
  

• Los Maestros comentan la razón para no hacerlo de otra manera

  /*
  
  I already tried obvious approaches A, B, and C to solve this problem.
  They didn't work for the following reasons: ...
  
  Therefore I wrote this less-than-obvious approach which works and 
  passes all unit tests.  
  
  */
  

Su "programador sénior" puede ser senior en términos de edad / longevidad, pero a mí me parece que tiene algo de profesional para crecer.

En cuanto a la depuración, hay mucho que decir sobre el código limpio y el uso liberal del registro y / o las declaraciones print() . Sin embargo, al usar un buen depurador, generalmente puedo encontrar el problema en una pequeña fracción del tiempo que llevaría sin él. Es una herramienta de poder. Úsalo.

  

Quiero forzar a la gente a leer el código. Odio a los depuradores por un   razón similar Son demasiado convenientes y te permiten pasar   código sucio con relojes y puntos de interrupción y encontrar el llamado   problema, cuando el verdadero problema era que hay errores en el código   porque el código no se ha simplificado lo suficiente.

Su programador senior parece tener un problema comprensible sobre el estilo de codificación . Sin embargo, está equivocado en cómo aborda el problema.

Ambos y la codificación descriptiva son esenciales: un código bien escrito con nombres descriptivos rápidamente le indica qué hace el código ; pero los comentarios le dicen lo que debe hacer el código (y por qué no, por qué lo hace de una manera y no otra . Luego tiene pruebas de unidad para verificar que el "contrato "(lo que el código debería haber hecho ) se cumple, y hágalo de manera automática, frecuente y sin ningún esfuerzo adicional por su parte.

Sin los comentarios, llevaría mucho tiempo (o una prueba de unidad, que en este punto sospecho que a su jefe le gustan incluso menos los comentarios, si cree que los errores pueden ser atrapados por personas que leen el código ) antes de encontrar el error:

// Multiply margin by a fixed amount.
page->margin += fixedMargin;

y, sí, el comentario podría estar equivocado, pero ahora sabes que en una de esas dos líneas hay un error . Esto, además de otro recurso útil, control de versión , le permite encontrar la discrepancia en menos de 30 segundos. Verificación de la salida e incluso el paso con un depurador podría no (por ejemplo, un valor de FixMargin de alrededor de 1.01 podría darle resultados ambiguos).

Si su mentor busca la simplicidad (estoy de acuerdo con él en que es un rasgo deseable), debería implementar alguna forma de verificar métricas como Complejidad ciclomática y establecimiento de objetivos métricos. Eso también se aplica a los comentarios: estoy de acuerdo en que no tiene sentido documentar cada línea de código, pero debe esforzarse por cubrir módulos, funciones y cualquier "punto WTF" en el código.

// Useless comment: multiply a by four

// Useful comment (even if maybe it shouldn't be in this exact point of code):
// Zooming 2:1, four pixels get mapped into one, divisor needs multiplying by four
a *= 4;

Su método puede dar resultados: en caso de que odie, tendrías un 20% de codificación y un 80% de documentación y pruebas. Con su método, obtienes 20% de codificación y 80% de depuración y rascado.

La diferencia entre los dos casos está, creo, en la moral y en la productividad general de las personas. Si documenta y simula las funciones y los módulos de manera adecuada, un que no necesite conocer la imagen global puede implementar un módulo, no tiene que estudiar los efectos secundarios en un escenario de caja negra, y para En conclusión, puede tener menos experiencia .

Al parecer, su mentor se siente cómodo acumulando una cantidad temible de deuda técnica . Revisaría sus estadísticas sobre el deslizamiento de fechas límite y / o ETAs; a menos que sea un milagro, cualquier proyecto de larga duración que no sea mantenido por una banda de un solo hombre o un grupo muy unido de amigos de codificación tendrá su deuda técnica tarde o temprano.

Si solo puede "leer el código", no tendrá una idea de lo que la función pretende hacer . Entonces, si alguien lo jode (sé que nadie lo hace, este es un caso hipotético) y hace algo mal, no tiene forma de verificarlo en el código. Tienes que esperar a que las pruebas unitarias lo detecten (si lo comprueban).

Agregue a eso, que no agregar comentarios me obliga a leer las funciones A1, A2, A3 ... de principio a fin, mientras que solo me interesa entender la función A, que llama a todo lo anterior.

Apostaría a que tu programador senior sea perezoso (malo) o que la gente se dé cuenta de lo hábilmente que él codifica (mucho peor).

  

Si pones comentarios, la gente no leerá el código tanto. Entonces los errores no son atrapados, y la gente no entiende las peculiaridades, cuellos de botella, etc. del sistema. Esto se proporciona siempre que los comentarios se actualicen con cambios de código, lo que, por supuesto, no está totalmente garantizado.

Nada como un idiota de opinión.

La próxima vez que esté comprando un libro para leer. Asegúrese de leerlo de principio a fin antes de comprarlo. De lo contrario, nunca sabrá exactamente si es lo que estaba buscando comprar. Eso es básicamente lo que te está diciendo que hagas.

Él ha hecho algunas suposiciones que son tontas.

1. Leer el código fuente te proporcionará la perspectiva purista de lo que hace.
2. Los comentarios se refieren al scope del código fuente al que están asociados.

Esa es su estrecha perspectiva sobre los comentarios, y como tal no ve ningún valor en ellos. Aquí están las limitaciones de no tener comentarios.

1. El código fuente es un conjunto de instrucciones para una computadora. No expresa conceptos o ideas. Por lo tanto, el código fuente nunca te dirá cuáles fueron los objetivos de los programadores. El código fuente que se compila sin errores y no se bloquea puede fallar en el cumplimiento de los objetivos. ¿Cómo sabrás algo diferente de la computadora leyendo el código fuente? La computadora ya lo hace, pero aún así podría no cumplir con el objetivo.
2. El código fuente no explica la intención del programador. open window, prompt for deposit no explica que el programador intentara comunicar una advertencia al usuario.

La próxima vez que tenga una conversación con este tipo, él le preguntará por qué agrega comentarios a su código fuente. Responde con esta declaración.

  

"Escribo el código fuente para decirle a la computadora qué hacer, y escribo comentarios para decirle a la gente qué hacer".

Los comentarios deben usarse como un registro escrito que explique algo confuso. Si está escribiendo algo que es potencialmente confuso y no se puede simplificar, por lo que sospecha que incluso le costará entenderlo seis meses después, escriba un comentario.

Si comenta generosamente, todo y en todas partes, entonces los comentarios pierden su eficacia para señalar las dificultades. (Recuerda la fábula del niño que gritó "¡Lobo!")

Los comentarios ocupan "pantalla de bienes raíces", a menos que tenga un buen editor de plegado; Tienes que seguir saltándolos cuando te mueves en el código. Y, por supuesto, los comentarios como /* increment i by one */ junto a i++ son basura completa.

Si el código es tan complicado que requiere una guía para las partes internas, entonces, por supuesto, escriba una guía para las partes internas. Llámelo README-internals.txt (o quizás HTML) y guárdelo en el mismo directorio que el código, e ingrese un comentario que diga /* this is all explained in README-internals.txt */ .

Acerca de los depuradores: cualquier herramienta que le ayude a encontrar un error es valiosa. Es tonto despedir herramientas. Los depuradores de punto de interrupción no deben usarse para verificar que el código está funcionando. Al menos, no se confía en como medio primario. Un depurador pasará alegremente una declaración como a[i] = i++ en C y confirmará una mala intuición.

Sin embargo, se puede confiar en las herramientas de depuración que realmente detectan algún tipo de violación en tiempo de ejecución como una herramienta de prueba. Si tiene un depurador que detecta el uso indebido de la memoria dinámica y el código pasa numerosos casos de prueba bajo ese depurador, es una fuente de confianza de que la memoria no se está utilizando incorrectamente.

Entonces, tenga en cuenta que "depurador" se refiere a más de un tipo de herramienta, no solo a un depurador de punto de interrupción / paso. Algunos depuradores solo proporcionan una vista del programa, lo que le permite razonar sobre lo que está mal, mientras que otros depuradores le buscan problemas.

El código no siempre se puede simplificar por no tener un depurador o negarse a usar uno. ¿Qué sucede si sigue la sugerencia de su jefe y simplifica el código hasta el punto de que ya no se puede simplificar más y aún necesita un depurador?

Me parece que la revisión del código es un proceso fantástico para responder a esta pregunta de manera concreta. Si leo la solicitud de atracción de alguien (haciendo un esfuerzo real por leerlo, no solo mirándolo con la actitud de que todo debe ser evidente de inmediato) y no puedo entender lo que hace, le digo a la gente que agregue un comentario. O puedes hacerlo solo con un pato de goma.

La mayoría de las personas saben de manera inofensiva qué ideas deben comentarse: es lo que le dirías a alguien que esté a tu lado si te hicieran una pregunta sobre el código. A menudo le pediré a alguien que explique algo en una revisión, dará una gran respuesta y mi respuesta es "Copie la explicación que acaba de escribir en un comentario en el código".

Pero por alguna razón, rara vez es el contenido que las personas terminan escribiendo en sus comentarios. En lugar de eso, la gente escribe cosas inane como

/**
 * Gets the {@link List} of {@link Author}s for the given {@link Book}.
 *
 * @param book The {@link Book} for which you want the {@link Author}s.
 * @return All of the {@link Author}s for the given {@link Book}.
 */
List<Author> getAuthors(Book book) { ...

y

// increment i by 1
i += 1

y ese es el tipo de cosas a las que los compañeros de trabajo experimentados están reaccionando. Yo mismo les digo a las personas cuando estoy revisando el código para eliminar este tipo de comentarios de bajo nivel que no agregan más información de la que se puede encontrar en las líneas que lo rodean inmediatamente.

Un ejemplo principal de una cosa trivial que necesita necesita ser comentada es la descripción de los tipos de pato en lenguajes dinámicos. Si el argumento o el valor de retorno de una función es un dictado con un montón de propiedades en él, más adelante te encontrarás con una locura si no comentas exactamente cuáles son esas propiedades.

Ninguna cantidad de comentarios elevará ningún código no trivial al nivel que un niño de 8 años pueda entender, por lo que no debe intentarlo. Debe hacer algunas suposiciones de que el lector sabe cómo leer el código, porque de lo contrario es un esfuerzo completamente inútil.

Finalmente, los comentarios son muy a menudo incorrectos. La gente a menudo los omite cuando lee, y no los actualiza cuando las cosas cambian. No puede escribir una prueba de unidad para sus comentarios, por lo que solo la forma de defender su código contra la podredumbre que se produce cuando sus compañeros de trabajo descuidados comienzan a hacer burla es comentar que solo las ideas son esenciales. Los comentarios que no agregan valor agregan valor negativo cuando se vuelven erróneos.

Diseño de documentos, ideas, arquitectura, historia, razón de ser, no líneas de código.

En un mundo perfecto sin plazos, su enfoque podría funcionar.

  

Un usuario informó un error en la aplicación X. Dejaremos que el nuevo usuario pase dos meses para obtener una comprensión profunda y exhaustiva del código, y luego tal vez agregar algunas semanas de refactorización. Si el error persiste, debería poder encontrarlo en ese momento y ni siquiera necesitará un depurador.

En el mundo real, esto suena como una forma confiable de salir del negocio.

Ejemplo de mal comentario

foo(); //calling function foo

Buen comentario

foo(); // must call function foo, because of a bug {link to bug}

Code Complete, el trabajo seminal sobre el estilo de codificación dedica varias secciones (comenzando con 19.3 en la edición 1) a la pregunta de los comentarios: lo bueno, lo malo y lo feo. Por lo tanto, usted y su desarrollador senior, probablemente deberían echar un vistazo allí.

Habiendo dicho eso, los comentarios bien escritos y bien colocados son muy importantes en la OMI, para cualquier proyecto a gran escala / a largo plazo.

En un mundo perfecto, es cierto que los comentarios no serían importantes . Pero a menos que tenga una memoria fotográfica y todos los que trabajan en su código son genios, los buenos comentarios solo ayudan a entender el código mucho más rápido cuando tiene que volver a él uno o dos años más tarde y modificarlo, o alguien más lo hereda. tu codigo. (Lo digo, después de haber trabajado profesionalmente durante 20 años y de 5 o 7 años en un proyecto con otros desarrolladores involucrados)

Hace unos años heredé una aplicación compleja que hace el trabajo pero que tiene una arquitectura deficiente y un estilo de codificación inconsistente e inflado. Afortunadamente, el código está bastante bien comentado, lo que me ahorró días y semanas para ponerme al día con ese código base.

Otra cosa que me ayudó a ponerme al día fue el depurador que uso. Cuando voy a analizar una nueva pieza de software en la que tengo que trabajar, una de las primeras cosas que hago es revisar todos los menús, hacer selecciones no válidas o extrañas y ver si puedo interrumpir la aplicación. Cuando lo rompo, ejecuto ese escenario con el depurador y veo a dónde me lleva esa falla. Casi invariablemente, esto me lleva a módulos y coyunturas importantes en el código base: una forma rápida de encontrar los lugares importantes en el mapa.

Aunque con mi propio código generalmente no tengo que usar mucho el depurador, hay ocasiones en las que ayuda, nadie es perfecto, incluso si son meticulosos con las pruebas de unidad (lo que a menudo es imposible cuando código heredado estrechamente acoplado.) Y si uso un nuevo módulo o componente, el depurador me ayuda a encontrar rápidamente los errores y malentendidos con los que tengo que lidiar para ayudarme a actualizar las nuevas cosas.

En resumen: el tiempo es dinero, y la mayoría de nosotros programamos entregar productos y pagar las cuentas . Pasar semanas y horas revisando cientos de líneas de código para encontrar un error que el depurador revelaría en 10 segundos, o un código mal escrito que podría estar iluminado por algunos buenos comentarios, no ayudará mucho a su línea de fondo ...

Su desarrollador senior aparentemente no se preocupa por la eficiencia y preferiría que los desarrolladores pasen horas y días jugando con código complejo, cuando unos pocos comentarios salvarían el día. Lo mismo ocurre con sus ideas sobre la depuración. (Solo curiosidad: ¿el desarrollador senior utiliza un IDE? ¿Por qué no escribe todo en un archivo de texto y hace una compilación y un enlace desde la línea de comandos, etc.? ¿Qué mejor manera de entender cada línea de código ...)

  

Los comentarios no dicen nada más que lo que el chico pensó   El código lo hace en el momento en que lo puso en el comentario

Ya sabes, es un enfoque extremadamente teórico. No me sorprendería, si lo dijera un matemático teórico, pero en los sonidos de un desarrollador senior no suena como si fuera alguien con una práctica muy larga.

Bueno, en teoría, puedes analizar el código en la cabeza, pero funciona solo con programas muy simples. Con los más complejos, de la vida real, te encuentras con el Detener el problema , que es uno de los problemas más complejos de la teoría de la computación. Si alguien dice que puede analizar programas en la cabeza, probablemente pueda hacer el desencriptado RSA en la memoria :)

Parece que su desarrollador senior no tiene experiencia en la vida real con problemas complejos, o está tratando de impresionarlo con trucos tomados de la película Hackers , o quiere justificar su propia pereza cuando se trata de escribir comentarios.