Mon client veut 25% de commentaires dans mon projet actuel, comment réagir? [fermé]

96

développeur junior ici.

Je travaille actuellement seul sur une application Web pour un gros client de mon entreprise. J'ai commencé le mois dernier. Le client souhaite au moins 25% de commentaires dans chacun de ses projets de logiciels.

J'ai vérifié le code des applications précédentes et voici mes observations:

  • chaque fichier commence par un bloc de commentaires (paquet, date de la dernière mise à jour, nom de ma société et copyright)
  • toutes les variables sont commentées avec leurs noms // nameOfCustomer public String nameOfCustomer

  • tous les getters et setters sont commentés

  • très peu de commentaires utiles

Il semble que les développeurs insèrent simplement le plus de commentaires possible pour atteindre ce seuil de 25%, quelles que soient leur qualité et leur utilité. Mon entreprise me dit que "nous le faisons comme le client le souhaite".

Je n'ai pas parlé directement avec le client à ce sujet. Voici mes arguments jusqu'à présent:

  • lignes inutiles pour lire et écrire (perte de temps)
  • les commentaires sont parfois non mis à jour (source de confusion)
  • les développeurs sont moins susceptibles d'utiliser ou de faire confiance à de vrais commentaires utiles

Quel est votre conseil à ce sujet? Comment dois-je gérer la situation?

Robin_
la source
162
C'est ridicule. Cependant, si c'est ce que le client veut et que le client vous paie beaucoup pour l'obtenir, c'est ce que vous lui donnez.
Robert Harvey
20
25% de lignes (ce qui signifie que vous ne mettez jamais de commentaire sur la même ligne que le code) ou 25% d' octets ?
RonJohn
10
Mieux vaut être prudent ici. Habituellement, il existe une raison derrière ce genre d’attente ... Si vous dites à votre client que ces commentaires sont inutiles, il / elle voudra peut-être 25% de commentaires (quelle qu’en soit la raison), mais maintenant SANS ceux que vous nommez comme inutiles .. vous risquez peut-être d'avoir plus de problèmes ... Parfois, les arguments des clients sont tellement convaincants que cela vous
déconcertera
19
C’est une leçon d’objet dans une règle que vous aurez amplement la chance d’observer dans votre carrière: ce que vous mesurez est ce que vous obtenez . Vous avez reçu une métrique pour les commentaires, et par conséquent, les commentaires sont ce que vous obtiendrez. Un client plus sensé vous donnerait des mesures de performance, d’exactitude, de robustesse et de coût, et vous obtiendriez ces informations. Mais vous n'avez pas de client sensible.
Eric Lippert

Réponses:

115

Toutes les autres réponses et commentaires ici m’ont vraiment bouleversé, parce qu’ils sont si contraires à ma première réaction et à l’attitude dont je suis témoin chez mes collègues. J'aimerais donc décrire une autre approche, ne serait-ce que pour être la voix dissidente .

Le principe directeur de cette réponse est "ravissez le client". Satisfaire le client ne signifie pas seulement répondre à ses attentes; cela signifie comprendre leurs demandes de manière si profonde que vous pouvez interpréter leurs propos de la manière dont ils les expriment et donner plus que ce qu'ils demandent. D'autres réponses semblent être guidées par le principe de conformité malveillante, que je trouve odieux; De plus, les pratiques commerciales sont discutables, car c’est un mauvais moyen de fidéliser les clients.

Pour moi, quand j'entends le client dire: "Je veux 25% de commentaires", c'est le début d'un dialogue. Pour moi, il est clair que l'implication ici est "je veux beaucoup de texte descriptif, pour que les nouveaux venus dans ce code puissent se mettre rapidement au travail", pas "je veux que vous ajoutiez de l'aléatoire à une certaine catégorie syntaxique" comme d'autres réponses semble être le prendre. Et je prendrais cette demande au sérieux et j'entendrais écrire de nombreux commentaires descriptifs et utiles, guidant un nouvel arrivant vers la structure du code, soulignant des décisions techniques surprenantes, décrivant le raisonnement suivi et donnant un niveau d'anglais de haut niveau. des descriptions de sections de code compliquées (même si elles n’ont pas de surprises). Cette intention et cette compréhension sont le point de départde la discussion - c'est avant même de commencer à parler. Pour moi, l’implication de la demande est tellement claire qu’elle n’a même pas besoin de cette clarification; mais si pour vous ce n'est pas clair, vous devriez bien sûr vous renseigner avec eux!

Bon, alors où va le dialogue si c'est le point de départ? La partie suivante du dialogue se présente comme suit:

  1. Je m'attendrais à ce qu'il s'agisse d'un effort supplémentaire sérieux, éventuellement dans une seconde phase du projet, au-delà de la production de l'outil qui les intéresse. Cela peut prendre plusieurs minutes de discussion pour discuter de ce processus et de la raison pour laquelle cela représente un travail supplémentaire, mais je vais l'omettre ici car, en tant que programmeur professionnel, je m'attends à ce que vous sachiez combien il est difficile de faire de bons commentaires.
  2. "Un effort supplémentaire sérieux" signifie que nous aurons peut-être besoin d'un budget-temps plus long et d'un budget monétaire plus important; ou nous pourrions avoir besoin de réduire le budget des fonctionnalités; ouil se peut que nous devions faire des compromis sur la qualité et la quantité des commentaires. Cette partie va être un peu une négociation. Mais à mon avis, vous devriez être très clair sur les coûts liés à ce travail supplémentaire et vous assurer que le fait de vouloir assumer ces coûts est une caractéristique tellement importante pour le client. Et s'ils le sont - génial! Vous gagnez du temps et de l'argent, et vos commentaires sont de grande qualité. Tout le monde gagne. Et s’il s’avère que la fonctionnalité de commentaire n’est pas si importante pour eux, ils sont prêts à perdre la capacité de brouiller les widgets ou à laisser l’échéance de la fin du délai de Granuary, 20x6, alors tout le monde gagne à nouveau: ils obtiennent le produit vous n'avez pas à passer l'effort supplémentaire nécessaire pour créer des commentaires de haute qualité.

Voici où je pense que le dialogue ne devrait pas aller:

  1. Ne menacez pas le client avec des commentaires de faible qualité. Laissez-les vous aider à choisir le niveau d'effort qu'ils souhaitent dépenser et qu'ils sont prêts à payer. Ne leur promettez pas 25% de commentaires et informez-les ensuite que vous avez l'intention de tenir cette promesse en générant automatiquement de manière aléatoire une fois le projet construit.
  2. Ne cache pas tes plans. Ne leur promettez pas 25% de commentaires, puis générez automatiquement du hasard sans leur dire que c'est ce que vous allez faire. Quand ils remarquent (pas si), vous perdez beaucoup d'argent: ils ne sont pas satisfaits du produit qu'ils ont obtenu et vous obtenez un bouche-à-oreille négatif.
  3. N'essayez pas de les convaincre qu'ils ne veulent pas de commentaires. Ils veulent clairement des commentaires. Discutez des compromis entre différentes approches: oui! Discutez des moyens alternatifs de rendre le nouveau code accessible aux nouveaux arrivants: oui! Dites-leur qu'ils ne savent pas ce qu'ils veulent: hein, non. Vous voulez travailler avec eux pour obtenir ce qu'ils veulent; alors comprenez ce que c'est et déterminez la meilleure façon de le leur fournir dans un budget qu'ils approuvent, en donnant la priorité aux fonctionnalités qui comptent le plus pour eux si les ressources dont ils disposent sont insuffisantes.
  4. Ne vous excusez pas sur la dureté des commentaires. L'écriture de code est difficile. le code de débogage est difficile; écrire des commentaires est difficile. Si c'était facile, ils ne vous engageraient pas. Ignorez les plaintes et allez droit au but, à savoir en quoi l'effort supplémentaire requis les affecte.
Daniel Wagner
la source
3
Belle prise positive sur la question :-)
cmaster
9
@ThorstenS. La société pour laquelle je travaille réalise la majeure partie de son travail dans le secteur de la défense. Peut-être voudrez-vous faire vérifier vos pouvoirs psychiques. De plus, je n'ai jamais dit "n'interprète pas leurs souhaits comme ils l'ont écrit": je traiterais les "commentaires à 25%" comme une demande sérieuse mais fortuite - la vraie demande est "un grand corpus d'écritures techniques" et 25% juste une indication sur le niveau d'effort auquel ils s'attendent d'aller dans cet organe, probablement choisi essentiellement arbitrairement, mais néanmoins une cible à ne pas manquer.
Daniel Wagner
12
Si je devais engager un programmeur, M. Daniel Wagner est le genre de gars que je voudrais engager.
Joe Gayetty
5
C’est une excellente réponse car elle cherche à identifier et à traiter l’intention de la demande par opposition à la lettre de la demande. IMO C'est la différence entre un développeur et quelqu'un qui écrit simplement du code.
Justin Ohms
6
Il serait également bon de préciser que ces commentaires augmenteront les coûts de maintenance . Une fois créés, ils doivent être constamment mis à jour , sinon ils sont une perte de temps et d’argent. (Attendre jusqu'à demain pour +1 afin que vous obteniez le représentant.;) Vous le méritez bien.)
jpmc26
83

Le client est roi. En tant qu’entrepreneur, vous devez donc respecter tout ce que le client a défini comme standard de qualité. Ou vous risquez de sortir.

Ceci étant dit, la définition des normes de qualité (ici médiocres) est primordiale:

  • Normes de qualité contractuelles: le code livré doit être conforme ou sinon, il s'agit d'une rupture de contrat. Pas le choix.

  • Normes de qualité d'entreprise formelles: même si cela fonctionne parfaitement, le code non conforme sera considéré par de nombreuses personnes comme étant de mauvaise qualité, vous serez donc vieux avant de les avoir tous convertis en une meilleure pratique. Pire: des outils bien connus peuvent être utilisés pour automatiser et légitimer de telles métriques de qualité (par exemple, le cube sonar ). Presque pas le choix.

  • Critères ad-hoc définis par un couple de personnes chez le client. Ici, vous pouvez engager une discussion. Il y a de l'espoir :-)

Dans ce dernier cas, il pourrait y avoir une certaine flexibilité, et vous pourriez essayer de faire valoir le point de vue diplomatique. Voici quelques arguments qui vont à l'encontre des critères du client:

  • Problème de productivité: le codage est effectué deux fois (une fois en anglais et une fois en code).
  • Problème d'exactitude: si des modifications sont apportées au code, elles doivent l'être dans les commentaires, sinon les commentaires pourraient devenir inutiles.
  • Problème de refactoring: l’outil de refactoring ne traite pas les noms de variables dans les commentaires.
  • Problème de risque: l'ambiguïté (ou l'obsolescence) des commentaires pourrait générer de la confusion et un risque d'augmentation des bugs.
  • La quantité n'est pas la qualité
  • Cette collection amusante de commentaires inutiles sur StackOverflow .
  • Cet article affirme qu'un taux de commentaire élevé pourrait même être le signe d'une odeur de code.

Mais au lieu de parler contre le mauvais et d’affronter le client, vous pourriez peut-être simplement promouvoir de meilleures approches:

  • Nettoyer le code (proposez le livre à votre client: une section convaincante est dédiée aux commentaires et au code auto-documenté).
  • Pratique de la documentation: les choses les plus difficiles à saisir, et donc les informations les plus précieuses, comme par exemple la relation et l'interaction entre les classes sont mieux documentées dans un document séparé (par exemple dans une image UML plutôt que 1000 mots de commentaires?)

Si le client n'est toujours pas convaincu, vous pouvez proposer une alternative expérimentale en utilisant des outils pour générer automatiquement une documentation avec des commentaires, tels que javadocou doxygen. Proposer avec cela de passer de la quantité (25% du code) à la qualité (générer un javadoc compréhensible).

Christophe
la source
7
Si le client est roi, cela prouve à quel point ces royautés sont inefficaces!
Steve
82
" Le client est roi. Ainsi, en tant qu'entrepreneur, vous rencontrerez tout ce que le client a défini comme standard de qualité. Sinon, vous risquez d'être absent. " C'est l'inverse qui a été mon expérience. Ceux qui donnent à leurs clients ce qu'ils pensent vouloir et non ce dont ils ont réellement besoin ne survivent pas très longtemps. En fait, je ne réserve cette forme d'abus qu'à de vrais clients à problèmes - et une deuxième dose n'a jamais été nécessaire.
David Schwartz
6
@ DavidSchwartz oui, certainement. Parfois, les clients pensent avoir besoin de quelque chose, mais en ont réellement besoin. Il appartient au consultant ou au développeur de convaincre, et 2/3 de ma réponse concerne précisément ce sujet. Mais tout dépend du contexte contractuel et du niveau de confiance entre le fournisseur et le client. Il faut donc rappeler à la règle du client (en fait, j’ai plusieurs fois rencontré des clients qui, après un long débat sur la solution optimale, j’ai soulevé cette phrase et cela a provoqué un changement soudain d’attitude et un réexamen soigneux des arguments ;-) ).
Christophe
7
"Problème de précision: si des modifications sont apportées au code, elles doivent l'être dans les commentaires, sans quoi les commentaires pourraient devenir inutiles." Je dirais que c'est encore pire qu'inutile . Un commentaire périmé peut se transformer en bogue (ou quelqu'un qui l'inverse parce qu'il pense que c'est un bogue) devient très rapide lorsque vous vous attendez à ce que ce soit la source de la vérité et que vous y fiez confiance.
Hamatti
11
@Hamatti En effet. Une fois, j'ai passé un temps considérable à déchiffrer l'intention originale derrière une ligne qui disait:i++; // count down
TKK
18

Le client souhaite au moins 25% de commentaires dans chacun de ses projets de logiciels.

Le client souhaite-t-il vraiment 25% de commentaires ou votre client souhaite-t-il que votre code soit aussi descriptif que possible?

IMHO, le client sait ce qu'il veut, mais pas ce dont il a besoin. En tant que client, ce n'est pas un développeur et reçoit les commentaires de ses propres employés / clients, votre client ne voit que la partie supérieure de l'iceberg.

Je suppose que votre client a une pseudo-connaissance et veut que le code soit bien documenté et facile à maintenir, et qu’il soit facile à maintenir, et l’outil utilisé est un commentaire (dans son esprit).

Essayez de lui parler et préparez des extraits de code avec du code bien écrit qui s’explique, et un autre mauvais avec des commentaires. Juste quelques lignes. Montrez-le si nécessaire et utilisez-le comme image pour vos mots.

Parlez à votre client / superviseur / peu importe et essayez de lui expliquer les principes modernes du contrôle de version (il n'est pas nécessaire de commenter au début du fichier) et de nettoyer le code (je recommande également le livre ) pour obtenir un code explicite.

Peut-être, si vous pouvez le montrer suffisamment et faire comprendre à votre client qu'il veut du code propre, pas seulement des commentaires, vous et votre équipe pouvez écrire un meilleur code (avec beaucoup moins de commentaires) et montrer immédiatement que vous êtes un bon développeur qui vaut la peine d'être gardé .

Chrᴉz
la source
13
Le code auto-explicatif est un principe charmant. Malheureusement, cela ne fonctionne pas très bien dans le monde réel. Les interfaces et les processus internes complexes doivent être documentés, et il ne suffit pas de choisir de bons noms. Quelles unités sont ces valeurs? Facteurs d'échelle? Taux d'échantillonnage? Quand est-il prudent d'appeler cette méthode et quand ne l'est-il pas? Quelles exceptions sont levées pour quelles conditions? Ainsi de suite. C'est ce qui rend votre code maintenable. Le monde réel présente une complexité qu'un extrait de code ne représentera jamais, et c'est pourquoi vous avez besoin de documenter cela correctement.
Graham
2
@ Graham Oui, les commentaires ne sont pas totalement inévitables. Mais les commentaires sont comme du code: plus vous en faites, plus il faut en assurer la maintenance. Rester concis aide je crois.
Robert Dundon
Je ne veux pas dire que certains somments sont complètement inutiles, mais des commentaires exactement comme le nom de la fonction ou la variable ne sont pas utiles. Le peu de code devrait montrer que c'est possible sans commentaires et ne devrait pas imposer un environnement sans commentaires. Si vous souhaitez montrer quelles exceptions sont levées ou décrire la fonctionnalité, vous pouvez utiliser la balise summary pour les fonctions. Si vous souhaitez signaler des dépendances, modélisez l'objet nécessaire en tant que paramètre d'entrée, etc. Il n'existe pas de moyen idéal pour tout faire, mais obtenez le meilleur des deux mondes
Chrᴉz
@Chriz Absolument, je suis d'accord. Si les commentaires n'apportent pas d'informations, laissez-les de côté. Mais comme je l'ai dit dans une autre réponse, le pourcentage n'est en réalité qu'un test d'odeur de code. Vous le justifiez, l'auditeur le vérifie, tout le monde passe à autre chose. Le problème est que quelqu'un pense que son code est vraiment explicite et n'a pas pensé à toutes ces choses.
Graham
12

Cela me rappelle ces réponses stupides Stack Overflow que vous voyez et qui consistent en une ligne suivie, littéralement, "du texte ici pour atteindre la limite minimale de caractères".

Lorsque cela se produit, des arguments peuvent être avancés selon lesquels deux groupes de personnes sont en faute:

  1. Les personnes qui mettent la limite - clairement, c'est excessif et empêche les personnes de soumettre leurs informations correctement formées sans ajouter de bruit artificiel

  2. Les personnes qui ont soumis des informations qui n'étaient pas correctement formées ont ensuite ajouté un bruit artificiel lorsque le système les a invitées à ajouter davantage de substance réelle

Parfois, une question sera à la fois simple et sur le sujet, et il n’ya rien de plus à dire que quelques mots. Cependant, c'est extrêmement rare. Dans presque tous les cas, il y a beaucoup plus de substance à dire. Si rien d'autre, il devrait être aveuglément évident que le moyen de contourner une restriction de caractère ne consiste pas simplement à vider du bruit aléatoire dans votre message.

Cette situation de commentaires à laquelle vous faites face est presque la même. Vos développeurs ont pris une demande de commentaires et l'ont implémentée en déversant du bruit aléatoire dans leur code. Le vandalisme est la documentation des noms de variables, juste à côté de la déclaration des variables . Cela n'aurait jamais dû arriver.

"Mais comment pouvons-nous atteindre 25%?" En écrivant des commentaires de fond. Utilisez plus de mots, de meilleurs mots, les meilleurs mots pour documenter l’effet des fonctions. Développez vos explications. Décrire les cas de bord plus en détail.

Cependant, pour revenir au point initial, le client est également partiellement fautif, car "25% du code source" est extrêmement arbitraire. En fin de compte, c’est le client, alors profitez-en. Mais je veux dire "meilleur". Pas "pire", comme cela s'est passé jusqu'à présent.

Courses de légèreté en orbite
la source
5

Je ne sais pas pourquoi il y a du bruit avec cette exigence.

Juste en faisant une doxygénation de base de votre code, vous êtes probablement déjà à environ 10%. Et prenons encore 5% des commentaires que vous avez écrits pour vous-mêmes (certains écrivent plus, mais 5% semble être une estimation prudente si vous n'avez pas fait vœu de silence). À ce stade, il est d'environ 15% (oui oui, je sais, 5% sur 90% est inférieur à 5%, ne coincez pas). Si votre taux d'oxygène est inférieur à 10%, peut-être que vos méthodes sont très longues. c'est généralement une bonne idée de les diviser en classes plus petites (principalement privées / protégées), ou d'utiliser des classes d'assistance plus génériques, etc.

Maintenant, pour le reste du texte de commentaire, placez les considérations de conception et les scénarios d'utilisation dans les commentaires de classe / fichier. Avoir quelques tables ou ASCII-art (ou un code doxygen qui génère des trucs plus jolis quand ils sont rendus). Je ne sais pas, bien sûr, de quoi parle votre projet, mais je pense que vous pouvez le faire sans commentaires factices (autres que le passe-partout de la doxygénation) et atteindre un taux proche de 25%.

S'il ne s'agit que de 20% et non de 25%, je suis sûr que le client vient d'indiquer ce chiffre comme étant quelque chose d'arbitraire et que tout ira bien. Quoi qu'il en soit, discutez avec eux de ce que les commentaires devraient englober; et montrez-leur un exemple de fichier commenté pour voir s'ils sont contents. Si tel est le cas, s'ils pensent qu'il manque quelque chose, ils vous diront ce qui manque. Ils ne vont pas vous dire "Nous ne pouvons suggérer aucun commentaire supplémentaire, mais nous souhaitons tout de même que vous en ajoutiez".

PS - Regardez le code des conteneurs Java standard pour voir comment vous pouvez atteindre, oh, environ 70% ...

einpoklum
la source
5

Avoir 25% de commentaires dans votre code est un excellent objectif, et cela rend le client heureux. Vous devez maintenant rédiger 25% de commentaires douteux tels que "i + = 1; // augmenter i de 1", prenez donc votre temps, écrivez des commentaires utiles et profitez du sentiment que vous êtes réellement payé pour faire quelque chose que vous devriez faire. en tous cas.

gnasher729
la source
C'est un bon aussi +1. Je ne sais pas s'il peut y avoir un bon objectif exprimé en termes de taux de commentaires, mais peut-être que beaucoup d'entre nous atteignent cet "objectif" de manière utile, sans le savoir ... J'ai récemment retrouvé un vieux code que j'ai écrit dans les années 80 au début de ma carrière, avec un algorithme innovant de haute performance: il n'a que 10% de commentaires, mais rétroactivement, j'aurais aimé y mettre plus de semelle ;-)
Christophe
4

Nous savons tous qu'il s'agit d'une exigence de merde. La question intéressante ici est

comment réagir?

Je crois fermement en la possibilité de rendre les problèmes visibles. Ici, j'utiliserais le fait que l'argent parle.

Demandez-moi de le faire et je vous assurerai que cela ajoutera 1% à mon offre. Oh, mais cela ajoutera 20% à toutes les offres de maintenance futures.

Une fois seulement, ils se demandent pourquoi je leur apprendrai que l’importance des noms propres est d’éviter les commentaires.

En guise d'alternative, je proposerai de créer une documentation visant à permettre à un programmeur de maintenance avec un ensemble défini de qualifications supposées de bien comprendre les idées qui sous-tendent le projet. Ou bien, je pourrais vous donner 25% de commentaires. Dépend de vous.

confits_orange
la source
3

Oui, je comprends votre frustration avec la règle stupide. J'ai lu beaucoup de programmes avec des commentaires inutiles comme

x = x + 1; // add 1 to x

Et je me dis, C’est donc ce qu’un signe plus signifie! Wow, merci de me l'avoir dit, je ne le savais pas.

Cela dit, le client paie la facture. Par conséquent, vous leur donnez ce qu'ils veulent. Si je travaillais chez un concessionnaire automobile et qu'un client me disait qu'il voulait une camionnette, je ne lui dirais pas s'il a réellement besoin d'une camionnette et le questionner sur ce qu'il compte y transporter. Je lui vendrais une camionnette.

D'accord, il y a des moments où ce que le client dit vouloir et ce dont il a vraiment besoin sont si éloignés l'un de l'autre que j'essaie de discuter de la question avec lui, peut-être de le convaincre d'accepter quelque chose de plus rationnel. Parfois cela fonctionne, parfois non. En fin de compte, si je ne peux pas changer d'avis, je lui donne ce qu'il veut. S'il revient plus tard et dit: «Oh, ça n'a pas vraiment répondu aux besoins de mon entreprise, alors nous pouvons le charger davantage pour faire ce que nous lui avons dit de faire la première fois. Le montant que vous pouvez négocier avec le client dépend de son degré de confiance en votre expertise, de la manière dont son contrat avec vous s’intègre à l’organisation et, franchement, de sa tête haussière.

Ce serait un cas très rare où, en supposant que ce fût à moi de décider, je perdrais un contrat parce que je pensais que les exigences étaient mal conçues.

N'oubliez pas que les personnes avec lesquelles votre entreprise négocie peuvent être ou non celles qui ont inventé cette règle des 25%. Ce pourrait être une règle qui leur est imposée d'en haut.

Je vois cinq réponses possibles:

Un. Convainquez votre patron ou celui qui négocie avec le client de se disputer à ce sujet. Les chances sont que cela ne fera rien, mais vous pouvez essayer.

Deux. Refuse de le faire. Cela va probablement vous faire virer, ou si l'entreprise est d'accord avec vous, vous faire perdre le contrat. Cela semble improductif.

Trois. Écrivez des commentaires inutiles pour remplir tout l'espace, le genre de commentaires qui ne font que répéter le contenu du code et que tout programmeur capable de modifier le code pourrait voir en 2 secondes. J'ai vu plein de commentaires comme celui-ci. Il y a des années, j'ai travaillé pour une société dans laquelle nous devions placer des blocs de commentaires devant chaque fonction répertoriant les paramètres, tels que:

/*
GetFoo function
Parameters:
  name: String, contains name
  num: int, the number
  add_date: date, the date added
Returns:
  foo code: int
*/
int GetFoo(String name, int num, Date add_date)

L'objection selon laquelle de tels commentaires constituent une charge de maintenance car vous devez les tenir à jour n'est pas valide. Il n'est pas nécessaire de les tenir à jour car aucun programmeur sérieux ne les regardera jamais. Si vous avez des questions à ce sujet, assurez-vous de bien préciser à tous les membres de l'équipe que les commentaires inutiles et redondants doivent être ignorés. Si vous voulez savoir quels sont les paramètres d'une fonction ou ce qu'une ligne de code fait, lisez le code, ne regardez pas les commentaires inutiles.

Quatre. Si vous souhaitez ajouter des commentaires redondants sans valeur, il est peut-être temps d'écrire un programme pour les générer. Un investissement initial, mais qui pourrait vous épargner beaucoup de dactylographie.

À mes débuts dans cette entreprise, une entreprise pour laquelle je travaillais utilisait un programme intitulé "Ecrit votre documentation pour vous! Une documentation complète pour chaque programme!" Le système exigeait que nous donnions à toutes les variables des noms essentiellement dénués de sens, puis que nous ayons une table donnant un nom significatif à chaque variable. La "documentation automatique" remplaçait donc fondamentalement le nom dénué de sens qu’elle nous obligeait à utiliser avec un nom explicite. Ainsi, par exemple - cela fonctionnait avec COBOL - vous auriez une ligne dans votre programme qui dit

MOVE IA010 TO WS124

et ils génèrent une ligne de "documentation" qui dit

COPY CUSTOMER NAME IN INPUT RECORD TO CUSTOMER-NAME IN WORKING STORAGE

Quoi qu’il en soit, on pourrait sûrement écrire un programme pour générer assez facilement une documentation aussi inutile. Lire une ligne comme

a=b+c

et générer le commentaire

// add b to c and save result in a

Etc.

Cinq. Tirez le meilleur parti de la règle stupide. Essayez d'écrire des commentaires utiles et significatifs. Hé, ça pourrait être un bon exercice.

Oh, au fait, puis-je ajouter que vous pouvez toujours jouer avec la métrique.

Je me souviens qu'une fois, un employeur avait déclaré qu'il allait commencer à mesurer la productivité des programmeurs en fonction du nombre de lignes de code que nous produisions par semaine. Quand on nous a dit cela lors d'une réunion, j'ai dit: super! Je peux facilement augmenter mon score. Plus d'écriture

x=x+4;

Au lieu de cela j'écrirai:

x=x+1;
x=x+1;
x=x+1;
x=x+1;

Boucles? Oubliez ça, je vais copier et coller le code dix fois. Etc.

Donc, ici, s’ils vont compter les lignes de commentaires, raccourcissez chaque ligne et continuez l’idée sur la ligne suivante. Si vous modifiez le contenu des commentaires, ne mettez pas à jour le commentaire existant. Mettez une date dessus, puis copiez le texte entier et écrivez "Mis à jour" et une nouvelle date. Si le client le questionne, dites-lui que vous pensiez qu'il était nécessaire de conserver l'historique. Etc.

Geai
la source
2

Les métriques arbitraires semblent être une réalité dans trop de projets ...

Cela se voit souvent dans des exigences stupides telles qu'une complexité cyclomatic maximale conduisant à un code plus complexe, car les fonctions sont inutilement divisées pour assurer la conformité, ou les fichiers sont scindés en raison d'une longueur SLoC arbitraire.

Les commentaires doivent ajouter au code et expliquer ce qui se passe (et non pas simplement répéter le code!).

Cela dit, si tel est le souhait de votre client et que votre société a accepté de le lui fournir, à moins que votre responsable QA ne développe une dose de bon sens, vous êtes bloqué.

Andrew
la source
Oui. Les règles arbitraires amènent les personnes à modifier leur comportement pour tirer parti de la règle. C'est le problème de la bureaucratie. Cela me laisse perplexe de voir comment les gens peuvent établir une règle et ne pas considérer que les personnes concernées par la règle peuvent en tenir compte pour décider quoi faire. Ensuite, ils font plus de règles pour combler les échappatoires, et plus de règles pour combler les échappatoires créées par les échappatoires, etc.
Jay
2

À court terme, il n'y a rien que vous puissiez vraiment faire. Aller avec elle.

Vous devriez également ignorer toutes les idées stupides que je vois dans ce fil à propos des protestations agressives passives et des blagues stupides dans le code.

Une fois que vous avez développé une relation de confiance avec le client, celui-ci sera mieux placé pour écouter votre raisonnement. Vous constaterez peut-être qu'il s'agit d'une demande idiote d'une personne qui exerçait autrefois une grande influence et qui bénéficie de très peu de soutien en interne.

En aucun cas, vous ne devriez vous y opposer sans la permission du client.

Gburton
la source
2

Je suis déçu par le manque d'imagination de mes collègues programmeurs ici.

Il me semble que le client a fait des recherches. Il a peut-être lu quelque part que le code de qualité contient généralement environ 25% des commentaires. De toute évidence, il se soucie / s’inquiète de l’entretien plus en aval. Maintenant, comment concrétise-t-il cela dans un document d’exigences qui doit être lié à un contrat? Ce n'est pas facile Cela peut même être impossible. Cependant, il veut s'assurer qu'il en aura pour son argent et énumère des indicateurs de qualité.

Cela ne me semble pas stupide ni ridicule. Les personnes qui ont rédigé les exigences ne sont probablement pas des programmeurs. Ils ont peut-être eu une mauvaise expérience avec un projet précédent. Leurs préposés à la maintenance se plaignent: "Rien de tout ça n'est documenté!". Il sonne dans les oreilles alors qu'ils écrivent de nouvelles exigences pour le prochain projet.

Si vous êtes sérieux au sujet de la documentation de votre code et de la mise en contexte du groupe de maintenance, cette exigence sera automatiquement remplie. Alors ne soyez pas une chatte à ce sujet!

En fin de compte, que ce soit 21% ou 29%, personne ne s'en souciera. Le client fera réviser vos données par un développeur indépendant et il comprendra mieux ce que vous avez fait.

Martin Maat
la source
1
La question prouve définitivement qu'exprimer un taux de commentaire comme objectif se retournera contre nous. Il aurait été plus efficace que le client ait pour objectif que le code soit compréhensible par un autre développeur (au sein de l'équipe? De l'extérieur? Avec quels antécédents de connaissances et de compétences?) Et donne les 25% comme directive (flexible). Exprimer cela de manière plus claire aurait été mieux compris par les contractants et aurait encouragé de meilleures solutions, telles que le code propre.
Christophe
0

J'ai rencontré beaucoup de programmeurs qui ne comprennent pas comment les gens existent et qui ne travaillent pas actuellement sur ce projet.

Pour eux, tout ce qu'ils savent, EST connu de tous.

Si quelqu'un ne sait pas TOUT ce qu'il sait actuellement, alors ces personnes sont des "idiots" pour lui.

Avec cette norme, vous pouvez forcer les gens à se mettre dans la peau de commentaires.

Ils écrivent peut-être des commentaires inutiles 99% du temps, mais parfois ils écrivent une des choses que "TOUT LE MONDE SAIT", et un nouveau membre de l'équipe ne passera peut-être pas 16 heures à chercher un bogue (que certains ont déjà résolu, mais a ensuite été annulé pour une autre raison), ce qui aurait été évident avec un commentaire à ce stade du code.

Avoir des commentaires sur des lignes avec des bogues non évidents peut également aider à éviter aux futurs programmeurs de casser complètement un programme par accident (surtout lorsque la partie "être cassé" n'est pas évidente lors d'un test rapide).

Si tout va bien utile
la source
3
Le problème avec laisser 10000 singes frapper des machines à écrire n’est pas qu’ils n’écrivent jamais quelque chose de précieux, mais que ces gemmes d’une rare rareté sont difficiles à trouver dans le tas de déchets.
Déduplicateur