Les commentaires de TODO ont-ils un sens? [fermé]

Je travaille sur un assez gros projet et j'ai la tâche de faire quelques traductions. Il y avait des tonnes d'étiquettes qui n'ont pas été traduites et alors que je cherchais dans le code, j'ai trouvé ce petit morceau de code.

//TODO translations

Cela m'a fait réfléchir sur le sens de ces commentaires pour vous-même (et les autres?), Car j'ai eu l'impression que la plupart des développeurs après avoir terminé un certain code et qu'il fait ce qu'il est censé faire, ils ne le regardent jamais tant qu'ils ne l'ont pas fait. pour le maintenir ou ajouter de nouvelles fonctionnalités. Pour que cela TODOsoit perdu pendant longtemps.

Est-il judicieux d’écrire ces commentaires ou faut-il les écrire sur un tableau blanc / sur un papier / quelque chose d’autre où ils restent au centre des préoccupations des développeurs?

J'ai tendance à utiliser des // todocommentaires pour des choses qui doivent arriver, mais je ne peux pas le faire immédiatement.

Je m'assure également de les pourchasser - je les recherche (Visual Studio a une fonctionnalité intéressante dans laquelle il répertorie ces commentaires pour vous) et veille à ce que tout soit fait.

Mais, comme vous le dites, tout le monde n’est pas assidu à leur sujet et, comme beaucoup de 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 des // todonotes postit ou un tableau blanc (où ils peuvent aussi ne pas finir en action).

Les IDE modernes reconnaissent les TODOcommentaires et, en tant que tels, ils sont visibles dans leur propre panneau / fenêtre / onglet, ils ne sont donc théoriquement pas perdus (je pense à Eclipse et à Visual Studio, je sais tous les deux assez pour savoir qu'ils le reconnaissent).

Vous pouvez même configurer des mots de commentaire supplémentaires tels que FIXME, BEWAREou 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 plus que souvent à quelque chose qui n’est pas nécessaire au bon fonctionnement de l’application "pour le moment". Et "pour le moment" peut durer de 5 minutes à 5 ans, selon le type / la taille du projet :-)

Enfin, à mon avis, il est toujours plus logique de les inclure dans le code, au bon endroit, en répondant précisément à la question "Où dois-je effectuer le changement" plutôt qu’en dehors du code.

Edit: Comme il est écrit dans l' article de Wikipédia sur les commentaires , y compris la date et le propriétaire du TODO est considéré comme une bonne pratique.

Cela peut sembler logique, du moins je les utilise parfois. Le point clé consiste à utiliser des balises cohérentes, telles que TODOou FIXMEpermettant de les retrouver facilement avec une simple recherche de texte.

Par exemple, les solutions "quick 'n dirty" sont pratiques à étiqueter, par exemple:

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. Si jamais il est temps d’embellir le code, il est facile de commencer par rechercher des FIXMEétiquettes.

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 les // todoentrées. Mais parfois, dans les grands projets, un attribut personnalisé est défini comme suit:

[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 hauts supérieurs peuvent venir les récolter automatiquement. C'est peut-être excessif pour le simple // todorappel, mais c'est efficace. En outre, cela nécessite une plate-forme .NET.

TODO est juste un sous-formulaire de commentaire. Les commentaires ont une grande utilité si l’écrivain est habile à 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'informant qu'une partie de mon code avait été retirée. J'étais plutôt impressionné par le fait qu'il était en production et qu'il avait survécu à la maintenance pendant 16 ans. Sachez donc que votre code pourrait durer très longtemps. Les commentaires sur l’intention, les besoins futurs, etc. peuvent aider dans des années à aider quelqu'un qui examine votre code pour la première fois.

Dans 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. Si oui, alors ils ont un sens. Si ce n'est pas le cas, ces commentaires ne sont qu'une perte de temps et vous voudrez peut-être examiner d'autres options, telles que les cartes récit.

Personnellement, j'utilise occasionnellement les 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, un, deux ou trois. Je les utilise plus comme un marqueur dans la base de code que toute autre chose. Si j'attends trop longtemps pour m'occuper d'eux, j'oublie ce que je pensais devoir faire.

Ma préférence serait toujours de ne pas les utiliser et d’utiliser des cartes d’histoires, des arriéré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, je ne les utilise maintenant que pour marquer les choses sur lesquelles je veux travailler, juste après avoir terminé mes tâches. Par exemple, j'implémente une nouvelle fonction et remarque qu'une fonction que j'utilise a un petit bogue; 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 / un bug / un problème pour eux. De cette façon, ils peuvent être hiérarchisés comme tous les bugs. Je pense que c'est beaucoup mieux que d'avoir quelques problèmes dans la base de données de bogues et dans le code en tant que TODO.

Vous pouvez éventuellement mettre un TODO avec l'ID de bogue :-).

Je pense que les TODOcommentaires, 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 dont vous vous rendrez compte qui seront nécessaires bientôt, mais que vous ne voulez pas faire le détour pour les mettre en œuvre immédiatement.

Ce qui devient moche, c'est quand de tels commentaires restent dans la base de code. Bien que vous travailliez activement sur une fonctionnalité, vous pouvez la laisser, mais dès que vous vous apprêtez à la compléter, vous devez vous concentrer sur son élimination. Si vous ne souhaitez pas les remplacer par des codes appropriés, utilisez au moins les fonctionnalités correspondantes. 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 retourne simplement la même chaîne que celle avec laquelle vous avez commencé. De cette façon, il y a un point clair pour l'expansion future, et vous savez que toute modification apportée sera reflétée 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 représenter une amélioration considérable de la facilité de maintenance.

Personnellement, j’utilise mon propre mot-clé au lieu d’être strictement TODO, bien que l’intention reste la même: marquer les éléments qui, je le sais, devront être revisités. De plus, avant de vérifier mon code, je fais une recherche globale du code source pour ce mot clé, choisi de telle sorte qu'il ne devrait normalement pas figurer dans le code. Si c'est trouvé, je sais que j'ai oublié quelque chose, et peut aller de l'avant et le réparer.

Pour ce qui est d'inclure le nom / la signature du programmeur avec le commentaire, je pense que c'est excessif si vous avez un système de contrôle de version du code source (c'est bien ça , non?). Dans ce cas, sa fonction de blâme vous indiquera qui a ajouté le commentaire ou, plus précisément, qui a enregistré en dernier un changement 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.

Si vous écrivez un TODO ou un FIXME avec l'idée que quelqu'un d'autre le corrigera lorsqu'ils découvriront ce code dans un avenir indéterminé, je dirais que cela ne vous dérange pas. Ils enlèveront le code et encombreront la partie rapport de votre IDE qui collecte ces informations.

Pour être utiles, ils doivent fournir un moyen de marquer votre code pour le (très) futur proche 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 le plus rapidement possible.

Tout ce qui a vécu plus longtemps devrait en fait être placé dans votre base de bogues à laquelle il appartient.

Il y a suffisamment de bruit dans nos vies, ne créons pas une nouvelle fanfare de choses qui crient à l'attention alors que c'est nécessaire ailleurs.

Mon 2 cent

D'habitude, je ne fais pas de commentaires // TODO, mais je les conserve tous dans un fichier séparé. Je n'arrive toujours pas à trouver / écrire un logiciel en ligne pour les gérer facilement. Les fichiers TODO sont donc toujours les plus utiles pour moi, car lorsque j'ouvre le projet peu de temps après, je ne sais plus quoi faire, puis je regarde dans le fichier TODO et je fais le travail. . J'ai "filename.cpp 354: Recoder ce bla bla bla" et c'est beaucoup plus utile que la recherche // commentaire TODO dans le fichier. J'avais // TODO earler quand j'étais paresseux, mais je viens de supprimer ces vieux // TODO-s du fichier source et je ne les répare pas lorsque le projet fonctionne bien. Je recommande fortement de déplacer tous les // TODO de la source vers un endroit séparé et de les conserver avec d'autres tâches afin que vous puissiez prioriser facilement les tâches. La priorité est vraiment difficile TODO lorsque vous avez tous vos TODO dans divers fichiers et projets.

Je trouve ça génial, mais pas seul. Par exemple:

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

Cette approche fonctionne assez bien avec parcimonie. Bien que je dois dire que prendre l'habitude de lancer des exceptions pour vous rappeler de compléter certains codes n'est pas vraiment l'approche la plus professionnelle. Mais cela m'a sauvé dans certains cas où vous pensez que vous avez terminé quelque chose et même écrit que vous avez terminé lorsque vous ne l'avez pas fait.

L'énorme avantage de la gestion des commentaires par rapport à l'un des millions d'autres façons de créer une liste de tâches est que les commentaires de la tâche sont accompagnés du code afin qu'ils ne puissent pas être séparés.

L'endroit le plus approprié pour ce genre de choses est probablement le suivi des problèmes plutôt que le code.

Je recommande fortement que chaque TODO ou FIXME soit inscrit dans un journal formel. S'ils ne le sont pas, ils sont facilement consultables et il devrait s'agir d'une phase de chaque itération pour rechercher les TODO et les FIXME en suspens. Celles-ci peuvent ensuite être cataloguées et définies comme solution immédiate, ou l'équipe peut planifier leur réparation au moment opportun.

Enfin, une fois résolus, ils doivent être supprimés - s'ils ne sont pas éliminés de manière systématique une fois résolus, ils perdent leur efficacité.

En bout de ligne: ils sont mieux que de ne pas enregistrer de problèmes du tout, mais vous devez en fait les entretenir.

En fait, IntelliJ vous alertera si vous essayez de valider du code comportant de nouveaux TODO. Donc, vous pouvez toujours interpréter un TODO comme "cela devrait vraiment arriver au moment où je commets".

Quand vous considérez le "TODO" comme une étiquette sémantique pour votre commentaire, je pense qu’ils ont un sens.

Dans les normes de codage de mon entreprise, nous spécifions que les initiales du développeur responsable doivent être incluses dans le TODO ( c’est -à- dire que je taperais "SAA TODO:"). Je pense que cela est utile, du moins en tant que convention, car sinon, la tentation de laisser du code non conforme à la norme TODO à la note du futur développeur sera traitée.

De manière utile, de nombreux IDE peuvent être configurés pour ajouter ces commentaires à une liste de tâches, leur permettant ainsi d'être traités de la même manière pour créer des wrnings sans être oubliés indéfiniment.

Une méthode plus odieuse, mais efficace, est probablement de transformer vos commentaires de tâches en messages de compilateur, de manière à ce que vous et tous les autres les voyiez lorsque le programme est compilé.

à Delphes:

{$message 'todo: free this thing when you know its not going to blow up'}

D'après mon expérience, TODOdevrait être utilisé pour indiquer qu'un morceau de code n'est pas utilisable et dire au lecteur ce qui est nécessaire pour le rendre utilisable (localement ou ailleurs).

TODOles annotations ne doivent pas être utilisées pour indiquer qu'une partie du code serait plus intéressante si elle était modifiée de quelque manière que ce soit. Les exemples incluent le code sale qui serait plus facile à gérer si réécrit ou une fonctionnalité supplémentaire dont personne n'a encore besoin. Ces annotations ont tendance à s'accumuler et à rendre grep TODOdes résultats inutiles.