¿TODOS los comentarios tienen sentido? [cerrado]

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?

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).

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.

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.

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.

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.

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.

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 :-).

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 ( sí , ¿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.

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

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.

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.

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.

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.

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".

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.

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'}

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.