If the comments are ugly, the code is ugly
De Framalang Wiki.
Article original sur IT World.
| Pseudo | Code | Rôle | Statut |
|---|---|---|---|
| Goofy | Traduction | hop fini | |
| aKa | Relecture | Terminé | |
| aKa | Validation | Terminé | |
| Mise en forme |
Article en ligne à l'adresse : http://www.framablog.org/index.php/post/2009/11/21/commentaires-code-source-programmation
Sommaire |
Titre
If the comments are ugly, the code is ugly
Si les commentaires sont moches, le code est moche
Paragraphe 1
Harsh words, I know, but I've come to believe it's true.
C'est un peu dur, je sais, mais finalement je crois que c'est vrai.
Paragraphe 2
Plone developer Martin Aspeli pointed me at a rather wise blog post in which a C programmer shared three rules he learned the hard way. The lesson that captured Martin's (and my) interest was this:
Le développeur de Plone Martin Aspeli m'a signalé un billet assez judicieux dans lequel un programmeur en C faisait part de trois règles apprises à ses dépens. Celle qui a particulièrement attiré l'attention de Martin (et la mienne) est la suivante :
Paragraphe 3
Good programs do not contain spelling errors or have grammatical mistakes. I think this is probably a result of fractal attention to detail; in great programs things are correct at all levels, down to the periods at the ends of sentences in comments.
Les bons programmes ne comportent aucune faute d'orthographe ni de faute de grammaire. Je pense que cela vient probablement d'une attention soutenue aux moindres détails ; dans les programmes excellents tout est correct à tous les niveaux, jusqu'aux points qui terminent les phrases de commentaires.
Paragraphe 4
"Aw, c'mon! You’re kidding!" You might think that nit-picking like this is beneath you, whereupon I will start pointing out errors in your code. It was embarrassing the first couple times this happened to me.
«- Allez, tu rigoles ou quoi ? ». Vous pourriez croire que pinailler à ce point est indigne vous, eh bien je m'en vais commencer à vous signaler les erreurs dans votre code lui-même. J'ai été bien embarrassée les deux ou trois fois où ça m'est arrivé.
Paragraphe 5
Programming, whether you're doing it as an open source enthusiast or because you're workin' for The Man, is an exercise in attention to detail. Someone who writes software must be a nit-picker, or the code won't work. Surely, you don't need me to cite the number of famous programming failures that were the result of a developer using a comma instead of a period, or random crashes caused by two lines of code in the wrong order?
La programmation, que vous la pratiquiez en enthousiaste de l'open source ou parce que vous êtes au service du patron, est un exercice qui exige de l'attention aux détails. Quiconque écrit un logiciel doit être pointilleux, sinon le code ne fonctionnera pas. Je suis sûre que je n'ai pas besoin de vous citer la série des célèbres bogues de programmation dont s'est rendu coupable un programmeur qui a utilisé une virgule et non un point, ou des plantages aléatoires provoqués par deux lignes de code placées au mauvais endroit ?
Paragraphe 5b
Perhaps my opinion is colored by my own role as a writer and editor, but I firmly believe that if you can't take the time to learn the syntax rules of English (including "its" versus "it's" and "your" versus "you're"), I don't believe you can be any more conscientious at writing code that follows the rules. If you are sloppy in your comments, I expect sloppiness in the code.
Il est possible que mon jugement soit faussé par mes fonctions d'écrivain et d'éditrice, mais je crois fermement que si vous ne pouvez pas trouver le temps d'apprendre les règles de syntaxe de la langue (y compris la différence entre « c'est » et « ces », ou encore « m'a » et « ma »), je ne crois pas que vous puissiez être beaucoup plus consciencieux pour écrire du code en respectant les bonnes pratiques. Si vos commentaires sont négligés, je m'attends à trouver du code négligé.
Paragraphe 6
My premise comes from something a very wise editor taught me, ten years ago (Laton McCartney, in case you're listening: Thanks!). If you can write the deck, he said, you can write the article very easily. If you can't write the deck, you don't understand yet what you have to say, and you shouldn't start writing. (The "deck" is that teaser or paragraph following the headline, which explains what the story is about and cajoles the reader into reading more.) Long-winded "explanations" of the code in the application's comments (that is, the ones that read like excuses), indicate that the developer probably didn't understand what he was doing. Which means that this is a prime candidate to be a bug farm.
Mon postulat vient de ce que m'a enseigné un éditeur très brillant, il y a dix ans (Laton McCartney, si tu lis ça : merci !. Si tu pex écrire le chapeau, disait-il, tu peux écrire l'article très facilement. si tu ne peux pas écrire le chapeau, c'est que tu ne comprends pas encore ce que tu veux dire, et tu ne devrais pas commencer à écrire (le « chapeau » est le petit paragraphe d'accroche qui suit le grand titre, qui dit en un mot de quoi il est question et invite gentiment le lecteur à en savoir plus). De filandreuses « explications » du code dans les commentaires de l'application (c'est-à dire, ceux qui se lisent comme des bonnes excuses) indiquent que le développeur ne savait probablement pas ce qu'il faisait au juste. Ce qui signifie que son code est éligible au titre de nid à bugs.
Paragraphe 7
Complaining about poor internal documentation is an old practice, but there's a reason that doing it right is important. Your comments are the only way you have to speak to the next person looking at this software (that may be you) about the larger scope of the software, not just this line-or-two. What were you thinking when you wrote this code? Yes, "self-documenting code" is a goal, but it's arrogant to assume that you've achieved it, any more than it's arrogant of me to assume that my words need no editing. (They do. I'm happiest when I have an editor.)
Se plaindre de la mauvaise documentation interne est un vieux refrain, mais il existe une raison pour laquelle il est important de la faire bien. Vos commentaires sont la seule façon dont vous disposez pour communiquer avec la prochaine persone qui regardera votre logiciel (il se peut même que ce soit vous) en profondeur, et pas juste une ligne ou deux. À quoi pensiez-vous en écrivant ce code ? D'accord, du code « auto-documenté » c'est l'idéal, mais c'est un peu arrogant de prétendre que vous l'avez atteint, et ça l'est tout autant de ma part si je prétends que mes phrases n'ont pas besoin d'être révisées (elles en ont besoin, je suis bien contente d'avoir un correcteur).
Paragraphe 8
Another common problem in comment ugliness is developers who update the code and don't update the comments; as one consultant pointed out, comments aren't tested. But doesn't that show a lack of attention to detail, too? Anytime you aren't paying full attention, you're apt to drop a logic bit.
Un autre problème habituel dans la médiocrité des commentaires apparaît lorsque les développeurs mettent à jour le code sans mettre à jour les commentaires ; comme l'a expliqué un consultant, les commentaires ne sont pas testés. Mais est-ce qu'il ne s'agit pas là encore d'un manque d'attention aux détails ? À chaque fois que vous n'êtes pas totalement attentif, vous êtes prédisposé à laisser tomber un petit bout de logique.
Paragraphe 9
Need a few examples?
From an explanation of a design choice. ("Yes, I can guess what was probably intended," wrote the programmer who showed me this example. "But therein lies the problem: I have to guess.")
"... questions designed to illicit a discussion..."Vous voulez quelques exemples ?
En voici un tiré d'une explication à propos d'un choix de conception. (« oui, je devine que c'était probablement intentionnel », a écrit le programmeur qui m'a montré cet exemple. « mais c'est bien là le problème : il faut que je devine ».)
«... des questions prévues pour injustifier un débat...»
Paragraphe 10
Here's an actual line of code with comment. Note how the comment highlights the spelling error. Not to mention that the comment tells you the programmer didn't have a clue of what he was doing in the first place. Especially since it shouldn't have been "finished" in that block of code; in that application, it should have tested against "complete".
if item.getState() == 'finsihed': #is this correct?
Voici maintenant une authentique ligne de code avec un commentaire. Notez que le commentaire met l'accent sur la faute d'orthographe. Sans compter que le commentaire vous indique que le programmeur n'avait pas la moindre idée de ce qu'il faisait au départ. Particulièrement parce qu'il n'aurait pas dû écrire « finished » (NdT : fini) dans ce bout de code, mais qu'il aurait dû essayer « complete » (NdT : terminé).
if item.getState() == 'finsihed': #est-ce correct?
Paragraphe 11
Yes, I allow for some exceptions. If English is not your first language, then it's possible that the comments you leave in your code will demonstrate any discomfort you feel in writing English. However, I haven't personally found this to be true. As many Americans have learned, "foreigners'" English skills are typically much better than our own. The developers I know whose English language skills are awkward are aware of it and they go to great lengths to ensure that an English speaker edits their documentation.
Bon, je vous accorde quelques exceptions. Si l'anglais n'est pas votre langue maternelle, il est possible que les commentaires que vous laissez dans votre code montrent que vous n'êtes pas à l'aise pour écrire en anglais. Cependant, en ce qui me concerne je n'ai pas trouvé que c'était le cas. Comme beaucoup d'Américains s'en sont rendu compte, les capacités en anglais des « étrangers » sont généralement bien meilleures que les nôtres. Parmi les développeurs que je connais, ceux qui ont des lacunes dans leur maîtrise de la langue anglaise en sont conscients et font tout leur possible pour qu'un anglophone passe en revue leur documentation.
Paragraphe 12
I won't go into code and comment indentation; that's a religious issue. But I've met developers who feel as strongly about "ugly" code formatting as I do about ugly grammar.
Je ne me lancerai pas dans des considérations sur l'indentation du code et des commentaires, c'est une guerre de religions. Mais j'ai rencontré des développeurs qui réagissaient aussi violemment devant un formatage de code « moche » que moi devant une grammaire moche.
Paragraphe 13
Modern development environments arguably have made it possible for developers to be sloppier without ill effect; a drag-and-drop interface might let you create a quick-and-dirty application (more dirty than quick, I fear) with fewer terrible side effects than back when software was typically written in Assembly language. Somehow, however, I can't see "I can be sloppy" as a true advantage.
Les environnements de développement modernes procurent la discutable possibilité aux développeurs d'être négligents sans effets pervers ; une interface glisser-déposer vous permet de créer une application vite fait bien fait (ou plutôt mal fait, j'en ai peur) avec bien moins d'horribles dommages collatéraux qu'à l'époque où les logiciels étaient généralement écrits en assembleur. Pourtant, d'une certaine façon, j'ai du mal à considérer le « je peux être négligent » comme un avantage réel.
Paragraphe 14
The "ugly" comment rule is just as true for internal business applications as it is for open source software. But FOSS developers need to pay more attention to it for two reasons. First, in a regular office, you very likely can find the programmer of the offending code and question him (or wallop him, if it was that bad). Also, in the open source community, more people look at the code and need to understand it.
La règle du commentaire « moche » vaut autant pour les applications propriétaires que pour les logiciels open source. Mais les développeurs de FOSS (Free Open Source Software, les logiciels libres et open source) doivent faire beaucoup plus attention encore pour deux raisons. La première, c'est qu'au bureau, vous avez de grandes chances de croiser le développeur du code mal fichu et de pouvoir lui poser des questions (ou de lui en coller une, si c'était vraiment horrible). De plus, dans la communauté open source, davantage de gens regardent dans le code et ont besoin de le comprendre.
Paragraphe 15
However, when I suggested to several developers that "if the comments are ugly, the code is ugly," many disagreed with me. You might, too. I'm interested in learning why, so I created a poll (let's see what everyone thinks!) and I invite you to leave a comment.
Toutefois, lorsque j'ai suggéré à des développeurs que « si les commentaires sont moches, le code est moche », beaucoup n'étaient pas d'accord. Et vous non plus peut-être. J'aimerais savoir pourquoi, et je vous invite donc à laisser un... commentaire.
