¿TODOS los comentarios tienen sentido? [cerrado]

86

Estoy trabajando en un proyecto bastante grande y tuve la tarea de hacer algunas traducciones para él. Hubo toneladas de etiquetas que no se han traducido y mientras buscaba el código encontré este pequeño fragmento de código

//TODO translations

Esto me hizo pensar en el sentido de estos comentarios para usted (¿y para los demás?) Porque tuve la sensación de que la mayoría de los desarrolladores después de que realizan un cierto código y hacen lo que se supone que deben hacer, nunca lo ven hasta que tienen para mantenerlo o agregar nueva funcionalidad. Para que esto TODOse pierda por mucho tiempo.

¿Tiene sentido escribir estos comentarios o deberían escribirse en una pizarra / papel / algo más donde permanezcan en el foco de los desarrolladores?

Ivan Crojach Karačić
fuente
2
(algunos) IDEs rastrean estos. Los uso generosamente cuando no he desarrollado completamente la implementación de un módulo, pero el contrato es satisfactorio para mí (u otros) para continuar el desarrollo de otra pieza relacionada.
smp7d
3
TODO para mí es más como "debería hacer para optimizar, pero innecesario enviar"
Jake Berger
8
Cada vez que pienso en una tarea que se debe hacer o en un caso límite que debe verificarse para la función actual en la que estoy trabajando, detengo lo que estoy escribiendo (incluso a mitad de declaración) y agrego un TODO para ello (incluso si es solo la línea de arriba) . Esto ayuda a prevenir esos errores "Oh, sí, incluso pensé en eso" . Antes de confirmar la función, verifico los TODO. Nunca se comprometen, pero desde que comencé a hacer esto, mi número de errores se ha reducido drásticamente .
BlueRaja - Danny Pflughoeft
8
Siempre uso #warning TODO: …si no quiero olvidar el TODO.
derecha el
2
@WTP: Visual Studio, R #, Netbeans, Eclipse, etc., etc., incluyen herramientas para ver todos los TODO dentro de una solución / espacio de trabajo. Ya no hay necesidad de ese viejo truco.
BlueRaja - Danny Pflughoeft

Respuestas:

107

Tiendo a usar // todocomentarios para las cosas que tienen que suceder, pero no puedo hacerlo de inmediato.

También me aseguro de perseguirlos: los busco (Visual Studio tiene una buena característica donde enumerará dichos comentarios para usted) y me aseguro de que se hagan las cosas .

Pero, como usted dice, no todos son diligentes con ellos y, como muchos comentarios, tienden a pudrirse con el tiempo.

Diría que esto es más una preferencia personal, siempre y cuando documente lo que debe hacerse y lo persiga, no importa si está en él // todo, si publica notas o una pizarra (donde también pueden terminar no siendo actuado).

Oded
fuente
18
Eclipse los resalta y también consolida una lista de ellos para usted. Y escribir un comentario TODO mientras el pensamiento está en su mente no es una mala idea, incluso si nunca llega a HACERLO. Alguna alma magnánima puede estar navegando por el código buscando cosas que hacer (OSS).
hobs
44
Resharper también tiene una buena lista de TODO, funciona mejor que el VS predeterminado (se ve en más archivos).
CaffGeek
Sí, dado un listado en su IDE, son útiles. De lo contrario, diría que tienen un uso muy limitado, ya que la base de código puede ser enorme.
Ingeniero
44
Debido a la putrefacción de los comentarios, siempre fecho e inicializo mis comentarios. Si el comentario tiene tres años de antigüedad de cuatro contratistas, probablemente pueda eliminarlo.
user1936
2
Dado que se mencionaron resharper y fechas, uso una plantilla simple de Resharper Live de "// TODO $ user $ ($ date $) -"
dark fader
56

Los IDE modernos reconocen los TODOcomentarios y, como tales, son visibles en su propio panel / ventana / pestaña, por lo que en teoría no se pierden (estoy pensando en Eclipse y Visual Studio, ambos sé lo suficiente como para recordar que lo reconocen).

Incluso puede configurar palabras de comentarios adicionales como FIXME, BEWAREo cualquier otra cosa que desee personalizar. Sin embargo, otros desarrolladores en su proyecto tendrán que personalizar su IDE de la misma manera.

Ahora, escribí "teóricamente" porque, aunque no se pierde, el TODO con más frecuencia se relaciona con algo que no es necesario para que la aplicación funcione correctamente "en este momento". Y "en este momento" puede extenderse de 5 minutos a 5 años, dependiendo del tipo / tamaño del proyecto :-)

Finalmente, en mi opinión, todavía tiene más sentido tenerlos en el código, en el lugar correcto, respondiendo con precisión la pregunta "¿dónde debo hacer el cambio" que en otro lugar fuera del código?

Editar: como está escrito en el artículo de Wikipedia sobre los comentarios , incluida la fecha y el propietario del TODO se considera una buena práctica.

revs Jalayn
fuente
32
Creo que la fecha y el dueño del TODO es solo ruido. Para eso es el control de versiones (y la función de culpa) (si realmente necesita la información).
sleske
3
No creo que una wikipedia que diga "Se aconseja" sea citable; olor a alerta Mejor enlace al artículo que afirma esto.
phresnel
@phresnel bueno, hay una cita vinculada a este "consejo", por lo que no sentí la necesidad de repetir esto aquí, de lo contrario, estoy de acuerdo con el hecho de que citar hechos de Wikipedia no respaldados por nada podría ser peligroso
Jalayn
@sleske Tendería a estar de acuerdo en mantener el ruido mínimo PERO creo que los IDE no le brindan automáticamente esa información del repositorio (a menos que me equivoque, tendría que comparar las versiones manualmente) si no la escribe explícitamente .
Jalayn
1
La función de "anotación" de Visual Studio hace que sea fácil ver quién realizó el último cambio en varias partes del archivo en el que está trabajando y con qué conjunto de cambios. No es perfecto, pero en muchos casos (particularmente con TODOcomentarios) lo suficientemente cerca como para ser útil.
un CVn
13

Puede tener algún sentido, al menos los uso a veces. El punto clave es usar etiquetas consistentes como TODOo FIXMEpara que se puedan encontrar fácilmente con una simple búsqueda de texto.

Por ejemplo, las soluciones "rápidas y sucias" son convenientes para etiquetar, algo como:

ConnManager.getConnection("mydatabase"); // FIXME: DB name should be configurable

Si el código hace lo que se supone que debe hacer, y nadie se queja, entonces el comentario no hace daño. Si alguna vez hay tiempo para embellecer el código, es fácil comenzar con la búsqueda de FIXMEetiquetas.

Joonas Pulakka
fuente
3
"FIXME" y "TODO" tienen diferentes significados para mí. Una traducción, un valor codificado o la captura de una excepción ex.printStacktrace()son TODO para mí. Por otro lado, FIXME trataría con la excepción que ocurre a veces, una pérdida de memoria u otro tipo de error que ha localizado pero que no se analizó / solucionó por completo.
rds
10

En mi industria, se alienta a los desarrolladores a hacer entradas JIRA (o etc.) en lugar de hacer comentarios porque no todos tienen la oportunidad de ver las // todoentradas. Pero a veces en proyectos grandes se define un atributo personalizado en la línea de:

[AttributeUsageAttribute(AttributeTargets.All, AllowMultiple = true)]
public class DeveloperNote : Attribute
{
    public DateTime EntryDate { get; set; }
    public string Description { get; set; }
    public DeveloperNote(int year, int month, int day, string desc)
    {
        EntryDate = new DateTime(year, month, day);
        Description = desc;
    }
}

Y luego se puede decorar un método de esta manera ...

[DeveloperNote(2011, 12, 13, "Make the db connection configurable")]

Y los superiores pueden venir y cosecharlos automáticamente. Puede ser excesivo para el simple // todorecordatorio, pero es efectivo. También requiere una plataforma .NET.

Garry
fuente
55
Un comentario TODO se convierte en una línea de código. Un boleto es más global y de mayor nivel, en mi opinión. Y creo que esta anotación es una exageración. TODO tiene más posibilidades de trabajar en más editores.
rds
66
Su industria? ¿Cual es ese? ¡¿No conozco toda una industria que fomente el uso de JIRA ?!
phresnel
7

TODO es solo un subformulario de comentario. Los comentarios tienen una gran utilidad si el escritor tiene alguna habilidad para saber qué transmitir y cómo transmitirlo. El sentido del humor también se puede aplicar aquí en pequeñas dosis para deleitar a los mantenedores años después.

Recibí una llamada el año pasado que parte de mi código estaba siendo retirado. Me impresionó bastante que hubiera estado en producción y sobrevivido al mantenimiento durante 16 años. Tenga en cuenta que su código podría durar MUCHO tiempo. Los comentarios sobre la intención, las necesidades futuras, etc. pueden ser de gran ayuda para ayudar a alguien que esté viendo su código por primera vez.

Pete Mancini
fuente
1
Si ha estado allí durante más de una década, no fue realmente necesario y, por lo tanto, agregar un TODOcomentario no tenía sentido.
un CVn
2
Eso supone que nunca cambian. Sin embargo, al igual que el código, los comentarios están sujetos a cambios con adiciones, eliminaciones y modificaciones. Es más probable que las listas TODO se cambien de esta manera. Estoy seguro de que en la última década desde la última vez que toqué el código, sus comentarios fueron cambiados.
Pete Mancini
6

En mi experiencia depende. El factor principal es si el equipo es o no lo suficientemente disciplinado como para seguir estos "pequeños" comentarios. Si lo hacen, entonces sí, tienen sentido. Si no lo hacen, estos comentarios son solo una pérdida de tiempo y es posible que desee buscar otras opciones, por ejemplo, tarjetas de historias.

Personalmente, uso los comentarios TODO ocasionalmente, pero generalmente son de corta duración y generalmente tengo solo un número muy pequeño de ellos, como uno, dos o tres. Los uso más como marcador en la base del código que cualquier otra cosa. Si espero demasiado para cuidarlos, entonces me olvido de lo que pensé que necesitaba 'hacer'.

Mi preferencia siempre sería no usarlos y, en su lugar, usar las cartas de historia o los registros pendientes o similares. Use un mecanismo para una tarea.

Manfredo
fuente
6

Solía ​​escribirlos en el pasado, pero descubrí que generalmente no los sigues.

Por lo tanto, ahora solo los uso para marcar cosas en las que quiero trabajar justo después de terminar con lo que estoy ocupado. Por ejemplo, implemento una nueva función y noto que una función que uso tiene un pequeño error; Hago un FIXME para arreglar esto para evitar descarrilarme en mi tarea actual.

Para ayudarme, nuestras compilaciones de CI están configuradas para fallar si hay FIXME en el código :-).

Si observa posibles problemas que no se pueden abordar de inmediato, abra un ticket / error / problema para ellos. De esa manera, se pueden priorizar como todos los errores. Siento que esto es mucho mejor que tener algunos problemas en la base de datos de errores y algunos en el código como TODOS.

Opcionalmente, puede poner un TODO con el ID de error :-).

sleske
fuente
3

Creo que los TODOcomentarios, hasta cierto punto, tienen sentido. Sobre todo si se está trabajando de forma iterativa (como es común en tiendas ágil y TDD), habrá cosas que reconoces está va a ser necesario en poco tiempo, pero que no desea hacer el desvío a aplicar en ese mismo momento.

Lo que se pone feo es cuando tales comentarios permanecen en la base de código. Mientras trabajas activamente en una función, está bien dejarla activada, pero tan pronto como te acerques a completarla, debes concentrarte en deshacerte de ella. Si no desea pasar por el trabajo de reemplazarlos con un código de trabajo adecuado, entonces, al menos, tenga en cuenta la funcionalidad relevante. Para tomar prestado el ejemplo de @ JoonasPulakka, donde el código dice inicialmente

ConnManager.getConnection("mydatabase"); // FIXME: DB name should be configurable

podrías cambiar eso a algo como

ConnManager.getConnection(GetDatabaseName());

con, por el momento, GetDatabaseName () es un código auxiliar que simplemente devuelve la misma cadena con la que comenzó. De esa manera, hay un punto claro de expansión futura, y usted sabe que cualquier cambio realizado allí se reflejará en cualquier lugar donde se necesite el nombre de la base de datos. Si el nombre de la base de datos es incluso moderadamente genérico, esto puede ser una mejora masiva en la mantenibilidad.

Personalmente, uso una palabra clave propia en lugar de estrictamente TODO, aunque la intención es la misma: marcar las cosas que sé que deberán revisarse. Además, antes de registrar mi código, realizo una búsqueda de código fuente global para esa palabra clave, que se elige de tal manera que normalmente no debería aparecer en ninguna parte del código. Si se encuentra, sé que olvidé algo, y puedo seguir y arreglarlo.

En cuanto a incluir el nombre / firma del programador con el comentario, creo que es exagerado si tienes un sistema de control de versión de código fuente ( , ¿verdad?). En ese caso, su función de culpa le dirá quién agregó el comentario, o más exactamente quién registró por última vez un cambio que tocó el comentario. Por ejemplo, en Visual Studio, esto se logra fácilmente utilizando la función "Anotar" que se encuentra entre las funciones de control de origen.

un CVn
fuente
3

Si escribe TODO o FIXME con la idea de que alguien más lo arreglará cuando lleguen a ese código en un futuro indeterminado, entonces diría que no se moleste. Ellos ensuciarán el código y desordenarán la parte de informes de su IDE que recopila esta información.

Para que sean útiles, deberían proporcionar un medio para marcar su código para el futuro (muy) cercano para que pueda volver al estado mental más rápido. En otras palabras, los coloca en su código solo para eliminarlos lo antes posible.

De hecho, cualquier cosa que se viva más tiempo debe colocarse en la base de errores donde pertenece.

Hay suficiente ruido en nuestras vidas, no creemos una nueva fanfarria de cosas que griten por atención mientras se requiere en otros lugares.

Mi 2 centavo

Newtopian
fuente
2

Por lo general, no hago // TODO comentarios, pero los guardo en un archivo separado. Todavía no puedo encontrar / escribir software en línea para administrarlos fácilmente, por lo que los archivos TODO siguen siendo los más útiles para mí porque cuando abro el proyecto, incluso después de poco tiempo, olvido qué hacer de vez en cuando y busco el archivo TODO y hago el trabajo . Tengo "filename.cpp 354: Recodifica este bla bla bla" y es mucho más útil que buscar // TODO comentario en el archivo. Hice // TODO earler cuando era flojo, pero simplemente elimino esos // TODO-s antiguos del archivo fuente y no los soluciono cuando el proyecto funciona bien. Recomiendo mover todos los // TODOs de la fuente a un lugar separado y mantenerlos juntos con otros todos para que pueda priorizar las tareas fácilmente. La prioridad es TODO realmente difícil cuando tienes todos tus TODOS en varios archivos y varios proyectos.

cnd
fuente
77
Y luego inserta una nueva función en filename.cpp, digamos alrededor de la línea 200 en el caso de su ejemplo, porque le resulta útil refactorizar algún fragmento de código. De repente tu referencia no tiene sentido. Prefiero que el IDE me indique dónde están ahora , no dónde estaban cuando vi la necesidad TODO.
un CVn
Sí, tienes razón) a veces es difícil para mí encontrar la línea, pero me ocupo de ella. Y si. Puedo usar ambos para encontrar fácilmente en el archivo o IDE, pero para saber qué hacer en un lugar separado.
cnd
2

Creo que genial, pero no solo. Por ejemplo:

//TODO: ADD MY CLICK EVENT LOGIC
throw new Exception();
//Even a simple messageBox could suffice

Este enfoque funciona bastante bien con moderación. Aunque tendría que decir que hacer un hábito de lanzar excepciones para recordarle que complete un código no es realmente el enfoque más profesional. Pero me ha salvado en algunos casos en los que cree que completó algo e incluso escribió que lo completó cuando no lo ha hecho.

Eduardo
fuente
2
En ese caso, simplemente podría lanzar un new NotImplementedException()que implica un ToDo.
CodesInChaos
En CI me gusta usar assert(0 && "TODO[cmaster]: Add click event logic");. Simple y muy efectivo para enviarme el mensaje si olvido el TODO ...
cmaster
1

La gran ventaja de los comentarios de tareas pendientes sobre cualquiera de los otros millones de formas en que uno puede crear una lista de tareas es que los comentarios de tareas viajan con el código para que no puedan separarse.

Sin embargo, probablemente el lugar más apropiado para cosas como esta es el rastreador de problemas en lugar del código.

Wyatt Barnett
fuente
0

Recomiendo encarecidamente que cada TODO o FIXME se ingrese en un registro formal. Si no lo son, se pueden buscar fácilmente, y debería ser una fase en cada iteración para verificar TODO y FIXME pendientes. Estos se pueden catalogar y establecer como remedio inmediato, o el equipo puede planear solucionarlos en el momento adecuado.

Finalmente, una vez reparados, deben eliminarse; si no se eliminan de manera sistemática después de resolverse, perderán su efectividad.

En pocas palabras: son mejores que no registrar problemas en absoluto, pero en realidad tienes que mantenerlos.

Marcin
fuente
-1

IntelliJ realmente lo alertará si intenta confirmar el código que tiene nuevos TODOs. Por lo tanto, siempre puede interpretar un TODO como "esto realmente debería suceder para cuando me comprometa".

ripper234
fuente
-1

Cuando considera el "TODO" como una etiqueta semántica para su comentario, creo que tienen sentido.

En los estándares de codificación de mi empresa, especificamos que las iniciales del desarrollador responsable deben incluirse con TODO ( es decir , escribiría "SAA TODO:"). Creo que esto es útil, al menos como una convención, porque de lo contrario existe la tentación de dejar un código deficiente con la nota TODO para que algún futuro desarrollador lo maneje.

De manera útil, muchos IDE se pueden configurar para agregar estos comentarios a una lista de tareas, lo que les permite ser tratados de manera similar para generar errores y no ser olvidados indefinidamente.

Stewart
fuente
-2

Probablemente, un método más desagradable pero efectivo es convertir sus comentarios de tareas pendientes en mensajes de compilación, de esa manera usted y todos los demás lo ven cuando se compila el programa.

en Delphi:

{$message 'todo: free this thing when you know its not going to blow up'}
Peter Turner
fuente
-4

En mi experiencia, TODOdebería usarse para indicar que un fragmento de código no es utilizable y le dice al lector lo que se necesita para hacerlo utilizable (localmente o en otro lugar).

TODOLas anotaciones no deben usarse para indicar que algún fragmento de código sería mejor si se modificara de alguna manera. Los ejemplos incluyen código sucio que sería más fácil de mantener si se reescribe o una característica adicional que nadie necesita todavía. Esas anotaciones tienden a acumularse y dan un grep TODOresultado inútil.

Martin Jambon
fuente
¿Es esta solo tu opinión o puedes respaldarla de alguna manera?
mosquito
Esta es mi opinión y consejos basados ​​en mi experiencia. Algunas personas usan los comentarios TODO para decir "Sé cómo escribir un buen código, pero no lo haré porque no me importa, pero bueno, escribí TODO aquí, así que realmente muestra que sé cómo escribir código limpio".
Martin Jambon