¿Por qué está mal comentar el código y luego eliminarlo gradualmente para realizar un seguimiento de lo que ya he hecho y lo que queda por hacer?

Siempre que descubro que es necesario cambiar una gran parte de mi código, ya sea porque es incorrecto o porque debe adaptarse a los principales cambios arquitectónicos necesarios por otros motivos, esto es lo que hago normalmente:

1. Comento todo el código que sospecho que podría tener que cambiar. Trato el código comentado como una especie de mi lista TODO.
2. Gradualmente reviso el código comentado y descomenta partes de este código, o los copio y pego en otro lugar y luego los edito según sea necesario, o reescribo partes de este código desde cero, mirando el código comentado como referencia. Cada vez que creo que he terminado con una parte del código comentado, lo elimino.
3. Continúo esto hasta que no puedo ver más código comentado.

Debo señalar que estoy haciendo esto en gran medida en el proyecto personal que estoy desarrollando solo.

Sin embargo, me dijeron que debería dejar de hacer esto. Me dijeron que, en cambio, debería comenzar a usar git, refiriéndome a las confirmaciones antiguas para ver el código antiguo, en lugar de dejar el código comentado. Me dijeron:

Comentar el código es un mal hábito que debería eliminarse. Te falta experiencia, así que no lo entiendes. Si, dentro de unos años, ve el código de otra persona a la que le gusta comentar el código, usted mismo comenzará a insultarlo. Cada vez que veo un código comentado, lo elimino en su totalidad, sin siquiera mirarlo, porque generalmente dicho código no tiene ningún valor. Ciertamente no podrá ver las desventajas de comentar el código en proyectos pequeños de una sola persona; pero si encuentras un trabajo y mantienes este hábito allí, será una pena.

¿Puedo preguntar cuáles son estas desventajas de lo que estoy haciendo que no puedo ver ahora?

Debo decir que no estoy realmente interesado en usar solo git para ver el código pasado. Como dije, trato de comentar el código como una especie de lista de tareas pendientes; mientras que git me mostrará cómo se veía el código, no podrá mostrarme claramente qué partes del código aún son necesarias para revisar y cuáles ya están hechas. Me temo que puedo perder parte del código e introducir errores.

Para completar, creo que debería agregar que la persona que estoy citando es un desarrollador experimentado y un fanático del "Código limpio" del tío Bob, y el tío Bob criticó comentar el código con dureza en su libro.

Si finalmente elimina todo el código comentado, no veo ningún problema real con esto. Dejar código comentado en su base de código es una mala práctica, pero eso no es lo que está haciendo si lo resuelve todo y lo elimina. Sospecho que la persona con la que está hablando no comprende el proceso que está utilizando o está siendo dogmática.

En realidad, el código comentado es inofensivo. El problema es que es desordenado y hace que sea difícil de leer. Hay pecados mucho peores, pero es una cosa muy simple de eliminar. Como la persona que comentó el código, usted está en la mejor posición para determinar si se puede eliminar por completo.

Muchos IDEs y editores de código entienden algún tipo de sintaxis 'TODO' en los comentarios. Esta es una forma alternativa de marcar lo que necesita ser cambiado. Es posible que desee considerar esto, ya que proporciona un poco más de información sobre lo que estaba pensando cuando lo marcó.

Al final del día, haga las cosas de la manera que resulte en el mejor resultado para usted. Incluso si este fuera un proyecto de equipo, siempre y cuando elimine todo el código comentado, no estará cargando a nadie más.

¿Puedo preguntar cuáles son estas desventajas de lo que estoy haciendo que no puedo ver ahora?

Podría decirse que ninguno si trabaja solo y no usa el control de versiones y siente que está bien hacerlo de esta manera.

De hecho, sin el control de la versión, no importa mucho lo que haga en cualquier momento del "tiempo", ya que el código siempre está en cualquier estado en que el archivo actual esté "guardado" como en el sistema operativo.

Si usa el control de versiones, y tiene una carga de comentarios como su "lista de tareas pendientes", y arregla algunos y elimina el comentario, luego repite, luego repite, etc., entonces tiene el código "trabajo en progreso" y los comentarios guardados en tu historial de revisiones. Esto no será un problema si nunca necesita retroceder a otra confirmación o incluso "selección de cereza" más tarde (por ejemplo, es donde toma confirmaciones específicas y las coloca en otra rama para usarlas). Pero de lo contrario podría ser un problema.

Podría decirse que esto se puede comparar con las "instantáneas" del software del disco duro, como lo hizo Windows (lo de Restaurar). Si toma una instantánea con un virus, mata el virus, pero luego necesita retroceder, puede volver a un punto donde el virus está presente nuevamente.

Es probable que este enfoque también sea ​​un problema cuando usas el control de versiones y trabajas con otros desarrolladores, ya que entonces tienen que ver tu lista de tareas pendientes que no les sirve. De hecho, es solo el desorden que tienen que ignorar y evitar. En nuestros equipos siempre eliminamos todos los comentarios, como código antiguo o "notas". A menos que sean útiles, sin embargo, esto es muy raro porque tenemos documentación sobre "cómo funciona" y un software para rastrear lo que hay que hacer (también conocido como todo).

Además, cuando trabaja en un proyecto más grande, tiende a colaborar, comprometerse y presionar con frecuencia, por lo que es posible que su rama en la que están trabajando tenga su lista TODO si fusionaron su rama con la suya. Entonces su lista TODO es asunto de todos: D

En resumen, si no trabaja solo y especialmente cuando usa el control de versiones, desordena el historial y puede estar desordenado para otros desarrolladores.

Y, esto es algo personal en algunos aspectos, pero usar una base de código como su "lista de tareas pendientes" no es realmente ideal. Un día puede dejar algo por accidente, u olvidar comentarlo o descomentarlo por error.

Al igual que con muchos enfoques de arquitectura, codificación y cómo trabaja usted o su equipo, cada escenario puede requerir algo diferente. Considere las desventajas mencionadas y los beneficios de usar el control de versiones, y decida si funciona para usted .

Parece que tu crítico es un poco dogmático. No estoy seguro de que insultar a alguien por comentar el código sea PC ;-), o incluso útil ;-)

Pero más en serio, creo que su crítico tiene razón, que debería considerar seriamente usar git (o algún otro sistema de control de fuente, pero git es una opción sensata).

Y eso puede aliviar algunas de sus necesidades para comentar el código.

Pero tener una lista TODO dentro del código (ya sea listas con viñetas o código antiguo) es bastante razonable en mi opinión. Pero es posible que desee reconsiderar un poco sobre cómo lo hace. Por un lado, sugiero pensar en otra persona que lea su código. Que alguien más podría ser usted, un año después de que abandone y vuelva a unirse a un proyecto. O podría ser alguien completamente distinto. SOLO encontrar código comentado es un poco confuso. Tal vez algo como:

/*
 * Need this sort of functionality added back before too long:
 * .... OLD CODE HERE
 */

Personalmente, me inclino más hacia algo como esto:

 * TODO:
 *      @todo   Possible get rid of intermediate LRUCache_ object.
 *
 *      @todo   Find some reasonable/simple way to get
 *              LRUCache<PHRShortcutSpec, PHRShortcutSpec, PHRShortcutSpecNoAuthCacheTraits_>   sRecentlyUsedCache (kMaxEltsInReceltlyUsedCache_);
 *              Working with ONE T argument
 *              Add(elt2cache).
 ...

y me siento libre de agregar 'fragmentos de código' del código antiguo como útil.

Usar git es difícil (tristemente). Le tomará un tiempo aprender y puede parecer que no es parte de lo que está tratando de lograr. Pero si va a programar de manera útil, necesitará aprender a hacerlo como parte de un equipo y comunicarse con un equipo, y git es exactamente cómo se hace hoy en día. Y una vez que haya comenzado a usarlo, encontrará que es una herramienta / muleta MUY útil, que facilita el desarrollo de su software.

¡La mejor de las suertes!

Hay muchas razones para comentar el código: -

• Todavía no está bien, y lo descomentará cuando esté listo.
• Lo estás comentando temporalmente para cambiar el comportamiento durante la depuración.
• No está seguro de si el código es necesario, pero no desea eliminarlo hasta que haya probado un poco más.
• El código es necesario para algunas versiones del software, pero no esta.
• El código está obsoleto, pero tardó años en escribirse y estás emocionalmente apegado a él. Además, podría ser útil algún día.

El problema surge cuando coloca el código en la cama y luego regresa a él un par de años después para realizar un mantenimiento. Encontrará la base de código llena de código comentado. Ya no estará claro por qué algo de eso está allí, y ahora es solo un desorden.

Si usa cualquier herramienta de control de versiones medio decente, puede eliminar audazmente cualquier código que ya no necesite, seguro sabiendo que el sistema de control de versiones todavía lo tiene guardado. Un archivo de diferencias entre versiones revelará lo que se eliminó. Una vez que haya implementado el control de versiones, la única necesidad de comentar es para cosas temporales. Si alguna vez encuentra código comentado en archivos en los que no está trabajando, simplemente puede eliminarlo.

No voy a reiterar por qué debería usar el control de fuente incluso para proyectos de una sola persona, ya que hay muchos otros recursos que le indicarán que haga esto. Pero una desventaja importante relacionada con su enfoque actual es que si comenta el código, lo oculta de su IDE (si no está usando un IDE, probablemente debería considerarlo).

Por ejemplo, si desea cambiar el nombre de un método o clase, o cambiar la cantidad de parámetros que toma un método, su IDE debe tener una opción de refactorización para hacer esto que encontrará todas las referencias apropiadas y las actualizará en consecuencia, pero probablemente ganó ' t buscar en los comentarios.

En lugar de tratar de adivinar dónde necesita hacer cambios, simplemente hágalos y deje que su IDE le diga dónde sus cambios han causado que las cosas se rompan. Luego puede comentar el código más quirúrgicamente y, con suerte, por un período de tiempo más corto antes de arreglar lo que se rompió.

Es malo y deberías parar .

La razón se reduce a intentar hacer una gran cantidad de refactorización de una vez.

Si comenta secciones grandes de código, arregle un poco y registre, entonces ha registrado un código no funcional. y toda una carga de cosas comentadas que otros asumirán que es antigua y puede ignorarse

Si no se registra con frecuencia, está acumulando conflictos de fusión y no registra el progreso paso a paso.

Debe cambiar su práctica de trabajo para que si tiene que detenerse a mitad de camino, todo siga funcionando.

Tome pequeños pasos y regístrese después de cada uno:

• extraer una interfaz
• escribe una prueba
• refactorizar una función

No marque grandes fragmentos de código como "suyos" al comentarlos y quítelos para trabajar solo hasta que estén completos o falle.

Si necesita realizar un seguimiento de lo que debe hacerse, use un tablero de tareas como scrum o trello