Écrivez-vous des titres dans les commentaires de code? [fermé]

Je parcourais un vieux code que j'avais écrit (première année à l'université) et j'ai remarqué que j'avais l'habitude d'écrire des titres de commentaires précédant diverses parties du code. Des trucs comme (cela vient d'un jeu Monopoly):

/*Board initialization*/
...code...

/*Player initialization*/
...code...

/*Game logic starts here*/
/*Displaying current situation*/
...code...

/*Executing move*/
...code...

/*Handle special event*/
...code...

/*Commit changes, switch to next player*/
...code...

Cela peut être redondant et sans doute inutile si le code est vraiment très clair, mais en parcourant le fichier, cela m'a surpris à quel point je me sentais comme si je savais ce qui se passait même si je ne regardais guère le code réel. Je peux certainement voir cela comme étant approprié dans certaines circonstances, alors je me demande - faites-vous cela? Pensez-vous que c'est une bonne idée? Ou est-ce trop?

C'est une odeur de code. Cela dit quoi et non pourquoi .

Si cela est nécessaire, divisez le code en petites fonctions.

Je fais ça tout le temps. À la fois pour marquer ce que fait le code, et probablement plus important, comme vous l'avez dit, pour faciliter la numérisation et la recherche d'un morceau de code. Parfois, aussi, j'écrirai un processus impliqué dans les commentaires, et «remplirai» le code sous les commentaires au fur et à mesure.

Je trouve intéressant le nombre de personnes qui n'aiment pas cette pratique sans vraiment pouvoir expliquer pourquoi. La raison pour laquelle de tels commentaires sont désapprouvés est qu'ils sont un signe que vous avez violé le principe de la responsabilité unique. Ce nom spécifique n'est généralement utilisé que dans un contexte OO, mais le concept général est également appelé cohésion et s'applique à d'autres paradigmes. Les écoles n'enseignent généralement pas ce genre de principes de conception jusqu'à la fin d'un programme d'études, voire pas du tout. En fait, certains enseignants imposent sa violation afin de rendre les choses plus faciles à noter en regroupant tout dans un seul fichier. Par conséquent, votre ignorance de première année est excusable, et le fait que vous ayez remarqué "quelque chose" de mal et essayé de clarifier avec des commentaires soit même louable dans les circonstances, mais en général, il est préférable de corriger une conception peu claire plutôt que d'essayer de la recouvrir de commentaires.

Je regarde ces choses comme un moyen de rendre le code plus clair ou non. Si vous pouvez dire sur la base des méthodes du fichier ce qu'est chaque partie, il n'est pas nécessaire cependant si vous devez avoir plusieurs sections, cela peut être utile. Peut-être lorsqu'un fichier de code devient trop volumineux, il doit être décomposé, ce qui pourrait réduire le besoin de tels commentaires.

Je dirais que si vous travaillez au sein d'une équipe pour trouver une norme, vous codez et commentez tous au moins de la même manière, il est donc plus facile de regarder le code.

Je le fais parce que je me communique souvent l'intention, ou que je mets essentiellement un signet pratique pour des choses comme «Le nettoyage des données commence ici». Habituellement, sous ce titre se trouve un bref résumé de la logique de ce que je fais et pourquoi.

J'aime la redondance. Si je perds mon cahier de laboratoire pour une raison ou une autre, ou si je dois revoir le code que j'ai écrit il y a des années, je n'aime pas devoir reconstituer ce que je faisais et pourquoi je le faisais. Si au moins une partie de cette logique est dans le code, elle est suffisamment documentée pour que je puisse au moins travailler avec elle à nouveau.

Je pense qu'une partie de mon inclination à ce sujet est une bonne partie de ma programmation est de nature statistique, et donc quelque peu répétitive. Alors qu'il y a peut-être quelques morceaux de code où j'ai une fonction bien nommée à rechercher, je pourrais avoir plusieurs dizaines d'utilisations assez similaires de quelque chose comme une fonction de modèle linéaire général. Il est utile de pouvoir aller chercher le code "quelle est la sensibilité des résultats au choix A par rapport au choix B ou C", et lequel était autre chose. C'est souvent accéléré par les titres.

Je pense que c'est utile dans des situations où vous avez des fichiers sources gigantesques avec des dizaines de fonctions et que vous pouvez les organiser librement en morceaux comme ça. Je ne dis pas que j'aime mieux que les fichiers source plus petits et plus ciblés cependant ...