comments - golang - Comentando el código eliminado
golang multiline comment (28)
También creo que es una sugerencia terrible :)
Debe usar el control de fuente y si elimina algún código, puede agregar un comentario cuando confirma. Entonces todavía tienes el historial de códigos si quieres ...
¿Es una buena práctica comentar el código que se elimina? Por ejemplo:
// Code to do {task} was removed by Ajahn on 10/10/08 because {reason}.
Alguien en mi grupo de desarrolladores durante una revisión por pares tomó nota de que deberíamos comentar las líneas de código que se eliminarán. Pensé que esta era una sugerencia terrible, ya que desordena el código con comentarios inútiles. ¿Cuál de nosotros tiene razón?
Agregaré mi voz al consenso: ponga los comentarios sobre por qué se eliminó el código en el repositorio de control de origen, no en el código.
Comentando el código no usado porque nunca se sabe cuándo tendrá que recurrir al código antiguo, y tal vez el código anterior ayude a otras personas a entenderlo, si fuera más simple en ese entonces.
Depende del motivo de la eliminación.
Considero que los comentarios son indicios de que las personas que mantienen el código en el futuro, si la información de que el código estaba allí pero se eliminó puede ser útil para alguien que mantiene el código (tal vez como un signo de "no hacer eso"), entonces debería estar ahí
De lo contrario, agregar comentarios detallados con nombres y fechas en cada cambio de código solo hace que todo sea ilegible.
En general, tiendo a comentar muy escasamente. Creo que un buen código debería ser fácil de leer sin mucho comentario.
También versiono mi código. Supongo que podría hacer diferencias en los últimos veinte checkins para ver si una línea en particular ha cambiado por una razón en particular. Pero eso sería una gran pérdida de tiempo para la mayoría de los cambios.
Así que trato de comentar mi código inteligentemente. Si se borra algún código por una razón bastante obvia, no me molestaré en comentar la eliminación. Pero si un fragmento de código se está eliminando por una razón sutil (por ejemplo, realizó una función que ahora está siendo manejada por un hilo diferente) comentaré o eliminaré el código y agregaré un comentario de banner por qué:
// this is now handled by the heartbeat thread
// m_data.resort(m_ascending);
O:
// don''t re-sort here, as it is now handled by the heartbeat thread
El mes pasado, me encontré con un código que había cambiado hace un año para solucionar un problema en particular, pero no agregué ningún comentario explicando por qué. Aquí está el código original:
cutoff = m_previous_cutofftime;
Y aquí está el código como se lo había arreglado inicialmente para usar un tiempo de corte correcto al reanudar un estado interrumpido:
cutoff = (!ok_during) ? m_previous_cutofftime : 0;
Por supuesto, surgió otro problema no relacionado, que pasó a tocar la misma línea de código, en este caso volviendo a su estado original. Entonces, el nuevo problema ya estaba solucionado, pero el problema anterior se volvió repentino. D''oh!
Entonces, ahora el código registrado se ve así:
// this works for overlong events but not resuming
// cutoff = m_previous_cutofftime;
// this works for resuming but not overlong events
// cutoff = (!ok_during) ? m_previous_cutofftime : 0;
// this works for both
cutoff = (!resuming || !ok_during) ? m_previous_cutofftime : 0;
Por supuesto, YMMV.
Es útil cuando se depura, pero no hay razón para verificar el código de esa manera. El objetivo del control de fuente es poder recuperar versiones antiguas sin saturar el código con código descompuesto.
Este es uno de esos elementos de Windows "rotos" como consejos / advertencias del compilador que no se han solucionado. te lastimará algún día y promueve la desidia en el equipo.
El comentario de verificación en el control de la versión puede rastrear qué / por qué se eliminó este código; si el desarrollador no dejó una nota, localícelos y estrangúlelos.
Estoy de acuerdo contigo Andrew; IMO esta es la razón por la que usa control de versiones. Con buenos comentarios checkin / commit y una herramienta diff, siempre puedes descubrir por qué se eliminaron las líneas.
Estoy de acuerdo en que es una sugerencia terrible. Es por eso que tienes el control de fuente que tiene revisiones. Si necesita volver atrás y ver qué se cambió entre dos revisiones, diferencie las dos revisiones.
Generalmente, el código que se elimina no se debe comentar, precisamente porque satura la base del código (y, ¿por qué se debería comentar algo que no existe?).
Su sistema de seguimiento de defectos o las herramientas de administración de control de origen son a dónde pertenecen dichos comentarios.
Hay algunas situaciones (raras) cuando comentar el código (en lugar de eliminar) es una buena idea. Aquí hay uno.
Tenía una línea de código que parecía buena y necesaria. Más tarde me di cuenta de que es innecesario y dañino. En lugar de eliminar la línea, la comenté y agregué otro comentario: "La línea siguiente es incorrecta por tal y tal motivo". ¿Por qué?
Porque estoy seguro de que el próximo lector del código primero pensará que no tener esta línea es un error e intentará volver a agregarla. (Incluso si el lector soy yo dentro de dos años.) No espero que primero consulte el control de fuente. Necesito agregar un comentario para advertirle sobre esta difícil situación; y tener una línea equivocada y la razón por la que está mal pasó a ser la mejor manera de hacerlo.
Nadie aquí ha escrito mucho sobre por qué no se debe dejar el código comentado, aparte de que parece desordenado. Creo que la razón principal es que es probable que el código deje de funcionar. Nadie está compilando. Nadie lo está ejecutando a través de pruebas unitarias. Cuando las personas refaccionan el resto del código, no lo están refabricando. Muy pronto, va a ser inútil. O peor que inútil: alguien podría descomentarlo, confiando ciegamente en que funciona.
Hay momentos en que voy a comentar el código, si todavía estamos haciendo un diseño / desarrollo pesado en un proyecto. En esta etapa, generalmente estoy probando varios diseños diferentes, buscando el enfoque correcto. Y a veces el enfoque correcto es uno que ya había intentado antes. Entonces es bueno que ese código no se pierda en las profundidades del control de fuente. Pero una vez que se haya resuelto el diseño, me desharé del código anterior.
Odio ver código desordenado con código comentado. Elimine el código y escriba un mensaje de confirmación que diga por qué se eliminó. Usas el control de fuente, ¿verdad?
No arroje basura al código activo con código muerto.
Parece que estás tratando de evitar versionar tu código. En teoría, suena como una gran idea, pero en la práctica puede ser muy confuso muy rápidamente.
Recomiendo encarecidamente comentar el código para depurar o ejecutar otras pruebas, pero después de que se haya tomado la decisión final, elimínelo del archivo por completo.
Obtenga un buen sistema de control de versiones y creo que encontrará que la práctica de comentar los cambios es complicada.
Si está eliminando el código. No debe comentar que lo eliminó. Este es todo el propósito del control de fuente (¿Estás utilizando el control de fuente? ¿Derecha?), Y cuando dices el comentario simplemente desordena el código.
Si está utilizando alguna forma de control de origen, este enfoque es algo redundante (siempre que se utilicen mensajes de registro descriptivos)
Sugeriría que, sí, es una buena práctica comentar el código que se ha eliminado pero no el código en sí .
Para aclarar aún más esta posición, debe utilizar un sistema de control de código fuente (SCCS) que permita algún tipo de comentario de check-in. Ahí es donde debe colocar los comentarios sobre por qué se eliminó el código. El SCCS proporcionará el historial contextual completo de lo que le sucedió al código, incluido lo que se ha eliminado. Al agregar comentarios de check-in, usted aclara esa historia.
Agregar comentarios directamente en el código simplemente lleva al desorden.
Debes eliminar el código siempre.
En cuanto a poder ver el código antiguo / eliminado, ese es el control de revisión.
El consenso reciente (de otras discusiones aquí) es que el código debería ser eliminado.
Personalmente comentaré el código y lo etiquetaré con una fecha o un motivo. Si está viejo / añejo y estoy revisando el archivo, entonces lo elimino. El control de versiones hace que volver sea fácil, pero no tan fácil como descomentar ...
Si se encuentra en medio de cambios importantes y necesita corregir una funcionalidad existente, comentar el código futuro es una medida razonable, siempre que observe que esta es una funcionalidad futura, al menos hasta que tengamos un control de código fuente amigable. sistemas.
Como única voz disidente, diré que hay un lugar para comentar el código en circunstancias especiales. A veces, tendrás datos que continúan existiendo que se ejecutaron a través de ese código anterior y lo más claro que puedes hacer es dejar el código anterior con la fuente. En tal caso, probablemente dejaré una pequeña nota indicando por qué el código anterior simplemente fue comentado. Cualquier programador que venga después podrá entender los datos aún existentes, sin tener que detectar psíquicamente la necesidad de verificar versiones antiguas.
Sin embargo, normalmente encuentro que el código comentado es completamente odioso y, a menudo, lo elimino cuando lo encuentro.
Creo que es bastante inútil y hace que el código sea menos legible. Solo piense cómo será después de algunos meses ...
// removed because of this and that
/*
removed this stuff because my left leg...
*/
doSomething();
// this piece of has been removed, we don''t need it...
Pasará media hora para descubrir qué está pasando
En donde estoy, comentamos el código anterior para un ciclo de publicación y luego eliminamos los comentarios después de eso. (Nos brinda la capacidad de solución rápida si parte del nuevo código es problemático y debe ser reemplazado por el código anterior).
Estoy de acuerdo en que no es una buena idea dejar el código eliminado en los comentarios.
El historial de códigos se debe ver a través de un sistema de control de versiones, que es donde se puede encontrar el código anterior, así como la razón por la que se eliminó.
Hay una práctica general de "código limpio" que dice que uno nunca debe mantener el código eliminado como comentado, ya que desordena y ya que su CVS / SVN lo archivaría de todos modos.
Si bien estoy de acuerdo con el principio, no creo que sea un enfoque aceptable para todas las situaciones de desarrollo. En mi experiencia, muy poca gente realiza un seguimiento de todos los cambios en el código y en cada check-in. como resultado, si no hay un código comentado, es posible que nunca se den cuenta de que alguna vez existió.
Comentar un código así podría ser una forma de ofrecer una advertencia general de que está a punto de ser eliminado, pero, por supuesto, no hay garantías de que las partes interesadas verán esa advertencia (aunque si trabajan con frecuencia con ese archivo, lo harán). Míralo).
Personalmente, creo que el enfoque correcto es factorizar ese código en otro método privado, y luego contactar a las partes interesadas relevantes y notificarles de la eliminación pendiente antes de deshacerse de la función.
La pregunta es, ¿por qué eliminas el código?
¿Es inútil? ¿Fue un error ponerlo allí en primer lugar?
No hay comentarios necesarios desde mi punto de vista.
En casi todos los casos, el viejo código debería ser eliminado y rastreado en su RCS.
Sin embargo, como todas las cosas, creo que hacer la afirmación "Todo el código eliminado SIEMPRE se eliminará" es un enfoque incorrecto.
Es posible que desee dejar el código anterior por una miríada de razones. La razón principal para dejar el código es cuando desea que cualquier desarrollador que esté trabajando en esa sección de código en el futuro vea el código anterior.
Confiar en el seguimiento de la fuente obviamente no da esto.
Entonces, creo que la respuesta correcta es:
-Borrar código antiguo a menos que lo deje proporciona información crucial que el próximo desarrollador en el código requeriría. Es decir, elimínelo el 99% del tiempo, pero no establezca una regla draconiana que elimine su capacidad para proporcionar la documentación necesaria al próximo desarrollador cuando las circunstancias lo justifiquen.
Una pequeña anécdota, por diversión: estuve en una empresa, hace algunos años, sin saber nada del control de la versión del código fuente (obtuvieron esa herramienta más adelante ...).
Así que tenían una regla, en nuestras fuentes C: "cuando haces un cambio, deshabilita el código anterior con macros de preprocesador":
#ifdef OLD /* PL - 11/10/1989 */
void Buggy()
{
// ...
}
#else
void Good()
{
// ...
}
#end
No hace falta decir que nuestras fuentes se volvieron rápidamente ilegibles. Fue una pesadilla mantener ...
Es por eso que agregué a SciTE la capacidad de saltar entre #ifdef / #else / #end anidados y tal ... Puede ser útil en casos más regulares.
Más tarde, escribí una macro de Visual Studio para deshacerme felizmente del código anterior, ¡una vez que obtuvimos nuestro VCS!
Ahora, como buti-oxa, alguna vez sentí la necesidad de indicar por qué eliminé algún código. Por el mismo motivo, o porque elimino el código anterior que siento que ya no es necesario, pero no estoy muy seguro (legado, legado ...). Obviamente no en todos los casos!
No dejo tales comentarios, en realidad, pero puedo entender la necesidad.
En el peor de los casos, comentaría en una versión y eliminaría todo en la próxima versión ...
En mi trabajo actual, para cambios locales importantes, dejamos el código anterior pero podemos reactivarlo por propiedades, en caso de emergencia. Después de probarlo en algún momento de la producción, finalmente eliminamos el código anterior.
Por supuesto, los comentarios de VCS son la mejor opción, pero cuando el cambio es de unas pocas líneas en un archivo grande con otros cambios, hacer referencia a la pequeña eliminación puede ser difícil ...