Mon client souhaite 25% de commentaires dans mon projet actuel, comment réagir?
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 logiciels.
J'ai vérifié le code des applications précédentes et voici mes observations:
- chaque fichier commence par un bloc de commentaires (package, date de dernière mise à jour, nom de mon entreprise et copyright)
toutes les variables sont commentées avec leurs noms
// nameOfCustomer public String nameOfCustomertous les getters et setters sont commentés
- très peu de commentaires utiles
Il semble que les développeurs placent autant de commentaires que possible pour atteindre ce seuil de 25%, indépendamment de la qualité et de l'utilité. Mon entreprise me dit que "nous le faisons comme le client le veut".
Je n'en ai pas parlé directement avec le client. Voici mes arguments jusqu'à présent:
- lignes inutiles pour lire et écrire (perte de temps)
- les commentaires ne sont parfois pas mis à jour (source de confusion)
- les développeurs sont moins susceptibles d'utiliser ou de faire confiance à de vrais commentaires utiles
Quel est votre avis à ce sujet? Comment dois-je gérer la situation?
Toutes les autres réponses et commentaires ici m'ont vraiment bouleversé, car ils sont si contraires à ma première réaction et si contraires à l'attitude dont j'ai été témoin chez mes collègues. Je voudrais donc décrire une approche alternative, ne serait-ce que pour être la voix dissidente .
Le principe directeur de cette réponse est "Enchantez le client". Faire plaisir au client ne signifie pas seulement répondre à ses attentes; cela signifie comprendre leurs demandes si profondément que vous pouvez interpréter ce qu'ils disent de la façon dont ils le pensent et livrer au-delà de ce qu'ils demandent. D'autres réponses semblent plutôt être guidées par le principe de la conformité malveillante, que je trouve odieux; et en plus, c'est une pratique commerciale douteuse car c'est un mauvais moyen d'obtenir des clients fidèles.
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, afin que les nouveaux arrivants dans cette base de code puissent être rapidement opérationnels", et non "Je veux que vous ajoutiez du hasard dans une certaine catégorie syntaxique" comme d'autres réponses semblent le prendre. Et je prendrais cette demande au sérieux et j'ai l'intention d'écrire de nombreux commentaires descriptifs et utiles, guidant un nouveau venu dans la structure du code, soulignant les décisions d'ingénierie surprenantes et décrivant le raisonnement qui y est entré, et donnant un 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épart de la discussion - c'est-à-dire avant même de commencer à parler. Pour moi, l'implication de la demande est si 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 connecter avec eux!
D'accord, alors où va la boîte de dialogue si c'est le point de départ? La partie suivante de la boîte de dialogue se présente comme suit:
- Je m'attendrais à ce que ce soit un effort supplémentaire sérieux, peut-être dans une deuxième phase du projet, au-delà de la production de l'outil dont ils se soucient. Cela peut prendre plusieurs minutes de discussion pour discuter de ce processus et pourquoi c'est un travail supplémentaire, mais je vais l'omettre ici parce qu'en tant que programmeur professionnel, je m'attends à ce que vous sachiez combien il est difficile de faire de bons commentaires.
- "Un effort supplémentaire sérieux" signifie que nous pourrions avoir besoin d'un budget plus long et d'un budget monétaire plus important; ou nous devrons peut-être réduire le budget des fonctionnalités; ou nous pouvons être amenés à 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 direct sur les coûts de ce travail supplémentaire et vous assurer que c'est une caractéristique si importante pour le client qu'il est prêt à assumer ces coûts. Et s'ils le sont - super! Vous obtenez du temps et de l'argent supplémentaires, et ils reçoivent des commentaires de haute qualité. Tout le monde gagne. Et s'il s'avère que la fonction de commentaire n'est pas si importante pour eux qu'ils sont prêts à perdre la capacité de fouetter les widgets ou à laisser la date limite glisser tardivement à Granuary, 20x6, alors tout le monde gagne à nouveau: ils obtiennent le produit qu'ils voulez, et vous n'avez pas à dépenser l'effort supplémentaire nécessaire pour créer des commentaires de haute qualité.
Voici où je pense que la boîte de dialogue devrait ne pas aller:
- Ne menacez pas le client avec des commentaires de mauvaise 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, puis informez-les que vous avez l'intention de tenir cette promesse en générant automatiquement l'aléatoire après la construction du projet.
- Ne cachez pas vos plans. Ne leur promettez pas 25% de commentaires, puis générez automatiquement le hasard sans leur dire que c'est ce que vous allez faire. Quand ils remarquent (pas si), vous perdez tous les deux beaucoup de temps: ils sont mécontents du produit qu'ils ont obtenu, et vous obtenez Word-of- négatif bouche.
- 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 d'autres façons de rendre le nouveau code de base convivial: oui! Dites-leur qu'ils ne savent pas ce qu'ils veulent: hein, non. Vous voulez travailler avec eux pour leur donner ce qu'ils veulent; alors comprenez ce que c'est et trouvez la meilleure façon de leur fournir cela dans un budget qu'ils approuvent, en priorisant les fonctionnalités qui leur tiennent le plus à cœur si les ressources dont ils disposent sont insuffisantes.
- Ne vous excusez pas sur la difficulté d'écrire des commentaires. L'écriture de code est difficile; le débogage du code est difficile; écrire des commentaires est difficile. Si c'était facile, ils ne vous embaucheraient pas. Ignorez simplement les plaintes et passez directement au point qui les intéresse, à savoir comment l'effort supplémentaire requis les affecte.
Le client est roi. Ainsi, en tant qu'entrepreneur, vous rencontrerez tout ce que le client a défini comme standard de qualité. Ou vous risquez d'être absent.
Cela étant dit, il importe beaucoup de définir les normes de qualité (ici pauvres):
Normes de qualité contractuelles: le code livré doit être conforme, sinon il s'agit d'une rupture de contrat. Pas le choix.
Normes formelles de qualité d'entreprise: même s'il fonctionne parfaitement, le code non conforme sera considéré comme de mauvaise qualité par tant de gens, que vous serez 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 mesures de qualité (par exemple cube sonar ). Presque pas de choix.
Critères ad hoc définis par quelques personnes chez le client. Ici, vous pouvez engager la 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 contredisent les critères du client:
- Problème de productivité: le codage se fait deux fois (une fois en anglais et une fois en code).
- Problème de précision: 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: car 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 risquer d'augmenter les bugs.
- La quantité n'est pas la qualité
- Cette drôle de collection de commentaires inutiles sur StackOverflow .
- Cet article qui fait valoir qu'un taux de commentaires élevé pourrait même être le signe d'une odeur de code.
Mais au lieu de parler contre le mal et d'affronter le client, pourriez-vous simplement promouvoir de meilleures approches:
- Code propre (suggérez le livre à votre client: il y a une section convaincante 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 commentaire?)
Si le client n'est toujours pas convaincu, vous pouvez proposer une alternative expérimentale, en utilisant des outils générant automatiquement de la documentation avec des commentaires, comme javadoc ou doxygen . Proposer avec cela de déplacer le focus de la quantité (25% du code) vers la qualité (générer un javadoc compréhensible).
Le client souhaite au moins 25% de commentaires dans chacun de ses projets logiciels.
Le client souhaite-t-il vraiment 25% des commentaires ou votre client souhaite-t-il que votre code soit aussi descriptif que possible?
À mon humble avis, le client sait ce qu'il veut, mais pas ce dont il a besoin. Comme un client n'est pas un développeur lui-même 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 et bon marché, et l'outil pour cela est les commentaires (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 mal écrit 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 leur dire les principes modernes du contrôle de version (pas besoin de commentaires au début du fichier) et du code propre (je recommande le livre aussi) et résultant ainsi un code auto-explicatif.
Peut-être que si vous pouvez le montrer suffisamment bien 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 mérite d'être conservé .
Cela me rappelle ces réponses stupides de débordement de pile que vous voyez qui consistent en une ligne suivie, littéralement, "de texte ici pour atteindre la limite de caractères minimale".
Lorsque cela se produit, des arguments pourraient être avancés selon lesquels deux groupes de personnes sont en faute:
Les personnes qui mettent la limite - clairement, c'est excessif et empêche les gens de soumettre leurs informations correctement formulées sans ajouter de bruit artificiel
Les personnes qui ont soumis des informations qui n'étaient pas correctement formées, ont ensuite ajouté du bruit artificiel lorsque le système les a invité à ajouter à la place une substance plus réelle
Parfois, une question sera à la fois simple et sur le sujet, et il n'y a pas grand-chose à dire de plus 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 à déverser du bruit aléatoire dans votre message.
Cette situation de commentaires que vous rencontrez est presque la même. Vos développeurs ont accepté une demande de commentaires et l'ont mise en œuvre en déversant du bruit aléatoire dans leur code. La documentation du nom des variables, juste à côté de la déclaration des variables, est vandalisme. Cela n'aurait jamais dû arriver.
"Mais comment pouvons-nous atteindre 25%?" En écrivant de véritables commentaires de fond. Utilisez plus de mots, de meilleurs mots, les meilleurs mots pour documenter l'effet des fonctions. Développez vos explications. Décrivez les cas Edge plus en détail.
Cependant, pour en revenir au point d'origine, le client est partiellement en faute ici aussi, car "25% du code source" est extrêmement arbitraire. En fin de compte, cependant, ils sont le client, alors profitez-en. Mais je veux dire "le meilleur". Pas "pire", comme cela s'est produit jusqu'à présent.
Je ne sais pas quel est le problème avec cette exigence.
Juste par doxygénation de base de votre code, vous êtes probablement déjà à 10% environ. Et prenons encore 5% des commentaires que vous avez écrits pour vous-même (certains écrivent plus, mais 5% semble être une estimation conservatrice si vous n'avez pas fait voeu de silence). À ce stade, c'est environ 15% (oui oui, je sais, 5% de 90% est inférieur à 5%, ne crachez pas). Si votre doxygène est inférieur à 10%, vos méthodes sont peut-être très longues; c'est généralement une bonne idée de les diviser en 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. Ayez des tableaux ou de l'art ASCII (ou du code doxygen qui génère des choses plus belles quand elles sont rendues). Je ne sais pas, bien sûr, de quoi parle votre projet, mais je pense que vous pouvez le faire sans commentaires fictifs (autres que le passe-partout de doxygénation) et atteindre quelque chose près de 25%.
Si c'est seulement, disons, 20% et non 25% - je suis sûr que le client vient de donner ce chiffre comme quelque chose d'arbitraire, et ça ira. Quoi qu'il en soit, discutez avec eux pour discuter de ce que les commentaires devraient englober; et montrez-leur un exemple de fichier commenté pour voir s’ils sont satisfaits. S'ils le sont, c'est tout, 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 possible mais nous voulons toujours que vous en ajoutiez".
PS - Regardez le code standard des conteneurs Java conteneurs) pour voir comment vous pouvez atteindre, oh, 70% ou plus ...
Avoir 25% de commentaires dans votre code est un excellent objectif à atteindre, et cela rend le client heureux. Maintenant, écrire des commentaires de remplissage de 25% comme "i + = 1; // augmenter i de 1" devrait être en dessous de vous, alors prenez 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 que c'est une exigence de merde. La question intéressante ici est
comment réagir?
Je suis un grand partisan de rendre les problèmes visibles. Ici, j'utiliserais le fait que l'argent parle.
Demandez-moi de le faire et je dirai que cela ajoutera 1% à mon offre. Oh, mais cela ajoutera 20% à toutes les futures offres de maintenance.
Ce n'est qu'une fois qu'ils ont demandé pourquoi je leur apprendrais que l'intérêt des bons noms est d'éviter la nécessité de commenter.
En guise d'alternative, je proposerai de créer une documentation visant à obtenir un programmeur de maintenance avec un ensemble défini de qualifications supposées à jour sur les idées derrière le projet. Ou bien, je pourrais vous faire 25% de commentaires. Dépend de vous.
Oui, je comprends votre frustration face à la règle idiote. J'ai lu beaucoup de programmes avec des commentaires inutiles comme
x = x + 1; // add 1 to x
Et je me dis, donc c'est ce que signifie un signe plus !! Wow, merci de me l'avoir dit, je ne le savais pas.
Mais cela dit, le client paie la facture. Par conséquent, vous leur donnez ce qu'ils veulent. Si je travaillais dans un concessionnaire automobile et qu'un client disait qu'il voulait une camionnette, je ne discuterais pas avec lui de la nécessité réelle d'une camionnette et je lui poserais des questions sur ce qu'il attend de lui. Je lui vendrais une camionnette.
D'accord, il y a des moments où ce que les clients disent vouloir et ce dont il a vraiment besoin sont si éloignés 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. Au final, si je ne peux pas changer d'avis, je lui donne ce qu'il veut. S'il revient plus tard et dit: Oh, cela ne répondait vraiment pas aux exigences de mon entreprise, alors nous pouvons lui facturer plus 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 la confiance qu'il accorde à votre expertise, de la façon dont son contrat avec vous s'intègre dans l'organisation et, franchement, de sa tête de taureau.
Ce serait un cas très rare où, en supposant que cela dépendait de moi, je perdrais un contrat parce que je pensais que les exigences étaient mal conçues.
Gardez à l'esprit que les personnes avec lesquelles votre entreprise négocie peuvent ou non être celles qui ont inventé cette règle des 25%. Ce pourrait être une règle qui leur serait imposée d'en haut.
Je vois cinq réponses possibles:
Une. Convainquez votre patron ou quiconque négocie avec le client d'en discuter. Il y a de fortes chances que cela n'accomplisse rien, mais vous pouvez essayer.
Deux. Refusez de le faire. Cela vous fera probablement virer ou, si l'entreprise est d'accord avec vous, vous fera perdre le contrat. Cela semble improductif.
Trois. Écrivez des commentaires inutiles pour remplir l'espace, le genre de commentaires qui répètent simplement ce qui est dans le code et que tout programmeur capable de modifier le code pourrait voir en 2 secondes. J'ai vu beaucoup de commentaires comme celui-ci. Il y a des années, j'ai travaillé pour une entreprise où nous devions mettre des blocs de commentaires devant chaque fonction répertoriant les paramètres, comme:
/*
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 valable. Il n'est pas nécessaire de les tenir à jour car aucun programmeur sérieux ne les examinera jamais. En cas de doute, assurez-vous de bien faire comprendre à 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 que fait une ligne de code, lisez le code, ne regardez pas les commentaires inutiles.
Quatre. Si vous souhaitez ajouter des commentaires inutiles redondants, il vaut peut-être la peine d'écrire un programme pour les générer. Quelque chose d'un investissement à l'avance, mais pourrait économiser un tas de taper sur la route.
À mes débuts dans cette entreprise, une entreprise pour laquelle je travaillais utilisait un programme annoncé comme "Écrit votre documentation pour vous! Documentation complète pour chaque programme!" Le système exigeait que nous donnions à toutes les variables des noms essentiellement dépourvus de sens, puis que nous ayons un tableau donnant un nom significatif pour chaque variable. Ainsi, par exemple - cela fonctionnait avec COBOL - vous auriez une ligne dans votre programme qui disait
MOVE IA010 TO WS124
et ils généreraient une ligne de "documentation" qui disait
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 également sans valeur. 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 idiote. 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 la métrique.
Je me souviens une fois qu'un employeur a dit qu'il allait commencer à mesurer la productivité des programmeurs par le 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;
J'écrirai plutôt:
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 comptent des lignes de commentaires, faites en sorte que chaque ligne soit courte et poursuivez l'idée sur la ligne suivante. S'il y a un changement dans ce qui se passe dans les commentaires, ne mettez pas à jour le commentaire existant. Mettez une date dessus, puis copiez le texte entier et écrivez "Mise à jour" et une nouvelle date. Si le client le remet en question, dites-lui que vous pensiez qu'il était nécessaire de conserver l'historique. Etc.
Les métriques arbitraires semblent être une réalité de trop de projets ...
Cela se voit souvent dans des exigences stupides telles qu'une complexité cyclomatique maximale conduisant à un code plus complexe, car les fonctions sont divisées inutilement pour garantir la conformité, ou les fichiers sont divisés car ils dépassent une longueur SLoC arbitraire
Les commentaires doivent ajouter au code et expliquer ce qui se passe (et pas seulement répéter le code!).
Cela dit, si c'est ce que veut votre client et que votre entreprise a accepté de fournir, à moins que votre responsable de l'assurance qualité ne développe une dose de bon sens, vous êtes coincé.
À court terme, il n'y a rien que vous puissiez vraiment faire. Allez-y.
Vous devez également ignorer toutes les idées stupides que je vois dans ce fil sur les protestations agressives passives et les blagues stupides dans le code.
Une fois que vous avez développé une relation de confiance avec le client, il sera mieux placé pour écouter votre raisonnement - vous pourriez constater qu'il s'agit d'une demande stupide d'une personne qui était autrefois influente et qu'elle a très peu de soutien en interne.
Vous ne devez en aucun cas vous y opposer sans l'autorisation du client.
Je suis déçu par le manque d'imagination dont font preuve 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 loin sur la route. 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. Pourtant, il veut s'assurer d'en avoir pour son argent et énumère donc certains indicateurs de qualité.
Cela ne me semble pas du tout stupide ou ridicule. Les personnes qui ont écrit les exigences ne sont probablement pas des programmeurs. Ils ont peut-être eu une mauvaise expérience avec un projet antérieur. Leurs gars de maintenance se plaignent: "Rien de tout ça n'est documenté!". Cela résonne dans les oreilles alors qu'ils écrivent de nouvelles exigences pour le prochain projet.
Si vous souhaitez sérieusement documenter votre code et fournir un contexte au groupe de maintenance, cette exigence sera remplie automatiquement. Alors ne soyez pas une chatte à ce sujet!
Au final, que ce soit 21% ou 29%, personne ne s'en souciera. Le client fera examiner vos données par un développeur indépendant et il ferait mieux de comprendre ce que vous avez fait.
J'ai rencontré de nombreux programmeurs qui ne comprennent pas comment existent les gens qui ne travaillent pas actuellement sur ce projet.
Pour eux tout ce qu'ils savent, IS connu de tous.
Si quelqu'un ne sait pas TOUT ce qu'il sait actuellement, alors ces gens sont des "idiots" pour eux.
Avec cette norme, vous pouvez forcer les gens à prendre l'habitude d'écrire des commentaires.
Ils peuvent écrire des commentaires inutiles 99% du temps, mais parfois ils peuvent en fait écrire l'une des choses que "TOUT LE MONDE SAIT", et quelqu'un de nouveau dans l'équipe pourrait en fait ne pas passer 16 heures à chercher un bug (que quelqu'un d'autre a déjà résolu, mais a ensuite été annulé pour une autre raison) 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 que les futurs programmeurs ne cassent complètement un programme par accident (en particulier lorsque la partie "en cours de rupture" n'est pas évidente lors d'un test rapide).