Les commentaires de TODO ont-ils un sens?
Je travaille sur un projet assez important et j'ai eu la tâche de faire des traductions pour lui. Il y avait des tonnes d'étiquettes qui n'ont pas été traduites et pendant que je parcourais le code, j'ai trouvé ce petit morceau de code
//TODO translations
Cela m'a fait réfléchir au sens de ces commentaires pour vous-même (et pour les autres?) Parce que j'ai le sentiment que la plupart des développeurs après avoir fait un certain morceau de code et qu'il fait ce qu'il est censé faire, ils ne regardent jamais cela jusqu'à ce qu'ils aient pour le maintenir ou ajouter de nouvelles fonctionnalités. De sorte que ce TODO sera perdu pendant longtemps.
Est-il judicieux d'écrire ces commentaires ou devraient-ils être écrits sur un tableau blanc/papier/autre chose où ils restent au centre des développeurs?
J'ai tendance à utiliser // todo commentaires pour des choses qui ont se produisent, mais je ne peux pas le faire immédiatement.
Je m'assure également de les poursuivre - je les recherche (Visual Studio a une fonctionnalité intéressante où il répertoriera ces commentaires pour vous) et je m'assure que les choses sont terminées.
Mais, comme vous le dites, tout le monde n'est pas assidu à leur sujet et comme de nombreux commentaires, ils ont tendance à pourrir avec le temps.
Je dirais que c'est plus une préférence personnelle - tant que vous documentez ce qui doit être fait et que vous le poursuivez, peu importe si c'est dans // todo, des post-notes ou un tableau blanc (où ils peuvent également ne pas être traités).
Les IDE modernes reconnaissent les commentaires TODO et ils sont en tant que tels visibles dans leur propre panneau/fenêtre/onglet, donc ils ne sont théoriquement pas perdus (je pense à Eclipse et Visual Studio, tous les deux j'en sais assez pour me souvenir qu'ils reconnais le).
Vous pouvez même configurer des mots de commentaire supplémentaires tels que FIXME, BEWARE ou tout autre élément que vous souhaitez personnaliser. Cependant, les autres développeurs de votre projet devront personnaliser leur IDE de la même manière.
Maintenant, j'ai écrit "théoriquement" car bien qu'il ne soit pas perdu, le TODO se rapporte le plus souvent à quelque chose qui n'est pas nécessaire pour que l'application fonctionne correctement "pour le moment". Et "en ce moment" peut s'étendre de 5 minutes à 5 ans, selon le type/taille du projet :-)
Enfin, à mon avis, il est encore plus logique de les avoir dans le code, au bon endroit, répondant précisément à la question "où dois-je faire le changement" que ailleurs en dehors du code.
Edit: Comme il est écrit dans Wikipedia article sur les commentaires , y compris la date et le propriétaire du TODO est considéré comme une bonne pratique.
Cela peut avoir un certain sens, au moins je les utilise parfois. Le point clé est d'utiliser des balises cohérentes telles que TODO ou FIXME afin qu'elles puissent être facilement trouvées avec une simple recherche de texte.
Par exemple, les solutions "rapides et sales" sont faciles à étiqueter, quelque chose comme:
ConnManager.getConnection("mydatabase"); // FIXME: DB name should be configurable
Si le code fait ce qu'il est censé faire et que personne ne se plaint, le commentaire ne fait aucun mal. S'il est jamais temps d'embellir le code, il est facile de commencer par rechercher les étiquettes FIXME.
Dans mon secteur, les développeurs sont encouragés à faire des entrées JIRA (ou etc) au lieu de faire des commentaires car tout le monde n'a pas la chance de voir le // todo entrées. Mais parfois, dans les grands projets, un attribut personnalisé est défini sur le modèle 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;
}
}
Et puis une méthode peut être décorée de cette façon ...
[DeveloperNote(2011, 12, 13, "Make the db connection configurable")]
Et les plus hauts peuvent venir et les récolter automatiquement. Il peut être exagéré pour le simple // todo rappel, mais c'est efficace. Il nécessite également une plate-forme .NET.
TODO n'est qu'un sous-formulaire de commentaire. Les commentaires ont une grande utilité si l'écrivain est doué pour savoir quoi transmettre et comment le transmettre. Un sens de l'humour peut également être appliqué ici à petites doses pour ravir les mainteneurs des années plus tard.
L'année dernière, j'ai reçu un appel m'indiquant qu'une partie de mon code était en cours de retrait. J'ai été plutôt impressionné qu'il soit en production et ait survécu à l'entretien pendant 16 ans. Soyez donc conscient que votre code pourrait durer LONGTEMPS. Les commentaires sur l'intention, les besoins futurs, etc., peuvent grandement aider quelqu'un qui, dans des années, consultera votre code pour la première fois.
D'après mon expérience, cela dépend. Le principal facteur est de savoir si l'équipe est suffisamment disciplinée pour donner suite à ces "petits" commentaires. S'ils le font, alors oui, ils ont du sens. S'ils ne le font pas, ces commentaires ne sont qu'une perte de temps et vous voudrez peut-être examiner d'autres options, par exemple cartes d'histoire.
Personnellement, j'utilise occasionnellement des commentaires TODO mais ils sont généralement de courte durée et je n'en ai généralement qu'un très petit nombre comme un, deux ou trois. Je les utilise plus comme marqueur dans la base de code qu'autre chose. Si j'attends trop longtemps pour m'occuper d'eux, j'oublie ce que je pensais avoir besoin de "faire".
Ma préférence serait toujours de ne pas les utiliser et d'utiliser à la place des cartes d'histoire ou des backlogs appropriés ou similaires. Utilisez un mécanisme pour une tâche.
J'avais l'habitude de les écrire dans le passé, mais j'ai constaté que vous ne les suivez généralement pas.
Par conséquent, maintenant, je ne les utilise que pour marquer les choses sur lesquelles je veux travailler juste après avoir terminé ce que je suis occupé. Par exemple, j'implémente une nouvelle fonction et remarque qu'une fonction que j'utilise a un petit bug; Je fais un FIXME pour résoudre ce problème afin d'éviter de dérailler dans ma tâche actuelle.
Pour m'aider, nos builds CI sont configurés pour échouer s'il y a des FIXME dans le code :-).
Si vous remarquez des problèmes potentiels qui ne peuvent pas être résolus immédiatement, ouvrez un ticket/bug/problème pour eux. De cette façon, ils peuvent être priorisés comme tous les bogues. Je pense que c'est bien mieux que d'avoir des problèmes dans la base de données de bogues et d'autres dans le code en tant que TODO.
En option, vous pouvez ensuite mettre un TODO avec l'ID de bogue :-).
Si vous écrivez un TODO ou un FIXME avec l'idée que quelqu'un d'autre le corrigera lorsqu'ils arriveront à ce code dans un avenir indéterminé, alors je dirais ne vous embêtez pas. Ils jetteront le code et encombreront la partie de rapport de votre IDE qui recueille ces informations.
Pour être utiles, ils devraient fournir un moyen de mettre votre code en signet pour le (très) proche avenir afin que vous puissiez revenir plus rapidement dans le bon état d'esprit. En d'autres termes, vous les placez dans votre code uniquement pour les supprimer dès que possible.
Tout ce qui a vécu plus longtemps devrait en fait être placé dans votre base de bogues où il appartient.
Il y a assez de bruit dans nos vies, ne créons pas une nouvelle fanfare de choses qui crient à l'attention alors qu'elles sont nécessaires ailleurs.
Mon 2 cent
Je pense que TODO commentaires, dans une certaine mesure, ont du sens. En particulier, si vous travaillez de manière itérative (comme cela est courant dans les magasins agiles et TDD), il y aura des choses que vous reconnaîtrez sont qui seront nécessaires avant longtemps mais que vous ne voulez pas faire le détour mettre en œuvre tout de suite et là.
Ce qui devient laid, c'est quand de tels commentaires restent dans la base de code. Pendant que vous travaillez activement sur une fonctionnalité, il est bon de les laisser, mais dès que vous vous approchez de la fin de la fonctionnalité, vous devez vous concentrer sur leur suppression. Si vous ne voulez pas passer par le travail de les remplacer réellement par un code de travail approprié, au moins, factorisez les fonctionnalités pertinentes. Pour emprunter l'exemple de @ JoonasPulakka, où le code dit initialement
ConnManager.getConnection("mydatabase"); // FIXME: DB name should be configurable
vous pourriez changer cela en quelque chose comme
ConnManager.getConnection(GetDatabaseName());
avec, pour le moment, GetDatabaseName () étant un stub qui renvoie simplement la même chaîne que celle avec laquelle vous avez commencé. De cette façon, il y a un point clair d'expansion future, et vous savez que toutes les modifications apportées seront reflétées partout où le nom de la base de données est nécessaire. Si le nom de la base de données est même modérément générique, cela peut être une amélioration massive de la maintenabilité.
Personnellement, j'utilise un mot-clé au lieu de strictement TODO, bien que l'intention soit la même: marquer les choses que je sais devront être revues. De plus, avant de vérifier mon code, je fais une recherche de code source global pour ce mot-clé, qui est choisi de telle sorte qu'il ne devrait normalement apparaître nulle part dans le code. S'il est trouvé, je sais que j'ai oublié quelque chose et je peux aller de l'avant et le réparer.
Quant à l'inclusion du nom/signature du programmeur dans le commentaire, je pense que c'est exagéré si vous avez un système de contrôle de version du code source (vous faites, non?). Dans ce cas, sa fonction de blâme vous dira qui a ajouté le commentaire, ou plus précisément qui a enregistré la dernière fois une modification qui a touché le commentaire. Par exemple, dans Visual Studio, cela est facilement accompli en utilisant la fonctionnalité "Annoter" trouvée parmi les fonctionnalités de contrôle de source.
Habituellement, je ne fais pas de commentaires // TODO mais je les garde tous dans un fichier séparé. Je ne trouve toujours pas/n'écris pas de logiciel en ligne pour les gérer facilement, donc les fichiers TODO sont toujours les plus utiles pour moi parce que lorsque j'ouvre le projet après un court laps de temps, j'oublie quoi faire maintenant et puis je regarde dans le fichier TODO et je fais le travail . J'ai "filename.cpp 354: Recode ce bla bla bla" et c'est beaucoup plus utile que de rechercher // TODO comment dans le fichier. J'ai fait // earler TODO quand j'étais paresseux mais je supprime juste ces // anciens TODO du fichier source et ne les corrige pas lorsque le projet fonctionne bien. Je recommande fortement de déplacer tous les // TODO de souce vers un endroit séparé et de les conserver avec d'autres todos afin que vous puissiez prioriser les tâches facilement. La priorité est une chose vraiment difficile à faire quand vous avez tous vos TODO dans divers fichiers et divers projets.
Je pense que c'est super, mais pas seul. Par exemple:
//TODO: ADD MY CLICK EVENT LOGIC
throw new Exception();
//Even a simple messageBox could suffice
Cette approche fonctionne plutôt bien avec parcimonie. Même si je dois dire que prendre l'habitude de lever des exceptions pour vous rappeler de compléter du code n'est pas vraiment l'approche la plus professionnelle. Mais cela m'a sauvé dans certains cas où vous pensez avoir terminé quelque chose et même écrit que vous avez terminé quand vous ne l'avez pas fait.
L'énorme avantage de faire des commentaires par rapport à n'importe quel autre million de façons de créer une liste de tâches est que les commentaires à faire voyagent avec le code afin qu'ils ne puissent pas être séparés.
L'endroit le plus approprié pour des trucs comme celui-ci est probablement le suivi des problèmes plutôt que le code.
Je recommande fortement que chaque TODO ou FIXME soit enregistré dans un journal officiel. S'ils ne le sont pas, ils sont facilement consultables, et cela devrait être une phase à chaque itération pour vérifier les TODO et FIXME en attente. Ceux-ci peuvent ensuite être catalogués et soit définis pour un remède immédiat, soit l'équipe peut planifier de les corriger au moment opportun.
Enfin, une fois corrigés, ils doivent être supprimés - s'ils ne sont pas éliminés de manière systématique après avoir été résolus, ils perdront leur efficacité.
Conclusion: ils valent mieux que de ne pas enregistrer les problèmes, mais vous devez en fait les maintenir.