¿Cuál es el mejor enfoque para los comentarios de código en línea?

13

Estamos refaccionando un código base heredado de 20 años, y estoy teniendo una discusión con mi colega sobre el formato de los comentarios en el código (plsql, java).

No hay un formato predeterminado para comentarios, pero en la mayoría de los casos las personas hacen algo como esto en el comentario:

// date (year, year-month, yyyy-mm-dd, dd/mm/yyyy), (author id, author name, author nickname) and comment

el formato propuesto para los comentarios futuros y pasados que deseo es:

// {yyyy-mm-dd}, unique_author_company_id, comment

Mi colega dice que solo necesitamos el comentario, y debemos reformatear todos los comentarios pasados y futuros a este formato:

// comment

Mis argumentos:

  • Lo digo por razones de mantenimiento, es importante saber cuándo y quién hizo un cambio (incluso esta información está en el SCM).
  • El código está vivo, y por esa razón tiene una historia.
  • Porque sin las fechas de cambio es imposible saber cuándo se introdujo un cambio sin abrir la herramienta SCM y buscar en el largo historial de objetos.
  • porque el autor es muy importante, un cambio de autores es más creíble que un cambio de autoría
  • Razones de agilidad, no es necesario abrir y navegar a través de la herramienta SCM
  • las personas tendrían más miedo de cambiar algo que alguien hizo hace 15 años, que algo que se creó o cambió recientemente.
  • etc.

Argumentos de mi colega:

  • La historia está en el SCM
  • Los desarrolladores no deben conocer el historial del código directamente en el código
  • Los paquetes tienen 15k líneas de longitud y los comentarios no estructurados hacen que estos paquetes sean más difíciles de entender

¿Cuál crees que es el mejor enfoque? ¿O tiene un mejor enfoque para resolver este problema?

    
pregunta Diego Alvarez 07.11.2012 - 21:53

2 respuestas

33

Comentarios generales

Soy un gran creyente en los comentarios de por qué (no cómo) . Cuando comienza a agregar comentarios acerca de cómo se encuentra en el problema, no hay nada que obligue a que se mantengan los comentarios en relación con el código (el por qué generalmente no cambia (la explicación del por qué puede mejorarse con el tiempo) ).

De la misma manera, date / authorInfo no le gana nada en términos de por qué el código se realizó de esta manera; al igual que la forma en que puede degenerar con el tiempo porque no hay ninguna aplicación por parte de ninguna herramienta. Además, la misma información ya está almacenada en el sistema de control de origen (por lo que está duplicando esfuerzos (pero de una manera menos confiable)).

Pasando por los argumentos:

  

Lo digo por razones de mantenimiento, es importante saber cuándo y quién realizó un cambio (incluso esta información se encuentra en el SCM).

Por qué. Ninguna de estas cosas me parece importante para mantener el código. Si necesita hablar con el autor, es relativamente sencillo encontrar esta información en el control de código fuente.

  

El código tiene vida, por eso tenía un historial.

El historial se almacena en el control de origen.
También confías en que el comentario fue escrito por esa persona. Los comentarios de How tienden a degradarse con el tiempo, por lo que este tipo de historial se vuelve poco confiable. Por otra parte, los sistemas de control de fuente mantendrán un historial muy preciso y podrá ver con precisión cuándo se agregaron / eliminaron los comentarios.

  

Porque sin la fecha de cambio es imposible saber cuándo se introdujo un cambio sin abrir la herramienta SCM y buscar en el largo historial de objetos.

Si confía en los datos de un comentario.
Uno de los problemas con este tipo de cosas es que los comentarios se vuelven incorrectos en relación con el código. Volver a la herramienta correcta para el trabajo. El sistema de control de origen hará esto correctamente sin necesidad de intervención por parte del usuario. Si su sistema de control de fuente es una molestia, entonces tal vez necesite aprender cómo usarlo de manera más apropiada (ya que esa funcionalidad suele ser fácil) o, si no lo admite, encontrar un mejor sistema de control de fuente.

  

porque el autor es muy importante, un cambio de authorx es más creíble que un cambio de autoría

Todos los autores (aparte de usted) son igualmente creíbles.

  

Razones de agilidad, no es necesario abrir una herramienta de navegación SCM

Si su herramienta de control de fuente es tan onerosa que está marchitando al usarla incorrectamente o (es más probable) está usando un conjunto incorrecto de herramientas para acceder al sistema de control de fuente.

  

la gente tendría miedo de cambiar algo que alguien hizo hace 15 años, que algo que se hizo de manera recesiva ...

Si el código ha durado 15 años, es más probable que sea más sólido que el código que solo ha durado 6 meses sin necesidad de revisión. El código estable tiende a mantenerse estable, el código con errores tiende a volverse más complejo con el tiempo (ya que la razón es que el problema no es tan simple como se pensó en un principio).

Más razones para utilizar el control de código fuente para obtener información.

  

El historial está en el SCM

Sí. La mejor razón aún.

  

Los desarrolladores no deben conocer el historial del código directamente en el código

Si realmente necesito esta información, la buscaré en el control de código fuente.
De lo contrario no es relevante.

  

Los paquetes tienen 15k líneas de longitud y los comentarios no estructurados son más difíciles de entender

Los comentarios deben ser una descripción de por qué estás haciendo algo de todos modos.
Los comentarios deben NO estar describiendo cómo funciona el código (a menos que el algoritmo no sea obvio).

    
respondido por el Martin York 07.11.2012 - 21:58
6

Apoyo firmemente a su colega. De todos modos, no podrá arreglárselas sin mirar el SCM si quiere comprender por qué se cambió algo a menos que guarde el código anterior en un comentario.

Si el código es demasiado complejo para ser comprendido sin escribir toneladas de comentarios, sugeriría invertir su energía en refactorización para hacer que el código sea legible / mantenible sin toneladas de comentarios.

Después de todo, contratas programadores, no narradores de historias ;-)

    
respondido por el Axel 07.11.2012 - 21:55

Lea otras preguntas en las etiquetas