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

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?

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:

3. 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.
4. 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.
5. 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.
6. 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.

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

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

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.

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

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.

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.

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.

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

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

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.

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