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

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

No hay un formato predeterminado para los 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 comentarios futuros y pasados ​​que quiero 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

• 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 eso 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
• la gente tendría más miedo de cambiar algo que alguien hizo hace 15 años, que algo que se creó o cambió recientemente.
• etc.

Los argumentos de mi colega:

• La historia está en la SCM.
• Los desarrolladores no deben conocer el historial del código directamente en el código
• Los paquetes tienen 15k líneas de largo 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?

Comentarios generales

Soy un gran creyente en los comentarios sobre por qué (no cómo) . Cuando comience a agregar comentarios sobre cómo cae en el problema de que nada impone que los comentarios se mantengan en relación con el código (el por qué generalmente no cambiará (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 hizo de esta manera; al igual que la forma en que puede degenerar con el tiempo porque no existe ninguna aplicación por parte de ninguna herramienta. Además, la misma información ya está almacenada en el sistema de control de fuente (por lo que está duplicando el esfuerzo (pero de una manera menos confiable)).

Pasando por los argumentos:

Digo por razones de mantenimiento, es importante saber cuándo y quién hizo un cambio (incluso esta información está 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 desde el control de origen.

El código tiene vida por eso tenía una historia.

La historia se almacena en el control de fuente.
También confía en que el comentario fue escrito por esa persona. Howlos comentarios tienden a degradarse con el tiempo, por lo que este tipo de historia se vuelve poco confiable. Los sistemas de control de fuente, por otro lado, mantendrán un historial muy preciso y podrá ver con precisión cuándo se agregaron / eliminaron 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 en 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 fuente hará esto correctamente sin necesidad de intervención del usuario. Si su sistema de control de fuente es un problema, entonces tal vez necesite aprender a usarlo de manera más adecuada (ya que esa funcionalidad suele ser fácil) o, si no lo admite, encuentre 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 y navegar por la herramienta SCM

Si su herramienta de control de fuente es tan pesada, la está utilizando incorrectamente o (es más probable) que esté utilizando el 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 recientemente ...

Si el código ha durado 15 años, entonces 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 el problema no es tan simple como se pensaba).

Aún más razones para usar el control de fuente para obtener información.

La historia está en la SCM.

Si. 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 largo y comentarios no estructurados, estos paquetes 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 NO deberían describir cómo funciona el código (a menos que el algoritmo no sea obvio).

Apoyo firmemente a tu colega. De todos modos, no pasará de largo sin mirar el SCM si desea comprender por qué se cambió algo a menos que mantenga el código antiguo en un comentario.

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

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