"Les commentaires sont une odeur de code"
Un de mes collègues pense que toute utilisation de commentaires dans le code (c'est-à-dire pas la méthode de style javadoc ou les commentaires de classe) est un odeur de code . Qu'est-ce que tu penses?
Seulement si le commentaire décrit ce que fait le code.
Si je voulais savoir ce qui se passait dans une méthode ou un bloc, je lirais le code. J'espère, de toute façon, que tout développeur travaillant sur un projet donné était au moins suffisamment familier avec le langage de développement pour lire ce qui est écrit et comprendre ce qu'il fait.
Dans certains cas d'optimisation extrême, vous utilisez peut-être des techniques qui empêchent quelqu'un de suivre ce que fait votre code. Dans ces cas, les commentaires peuvent et doivent être utilisés pour expliquer non seulement pourquoi vous disposez de telles optimisations, mais aussi ce que fait le code. Une bonne règle de base serait de demander à quelqu'un (ou à plusieurs autres personnes) familier avec le langage d'implémentation et le projet de regarder votre code - s'il ne comprend pas à la fois le pourquoi et le comment, alors vous devriez commenter le pourquoi et le le comment.
Cependant, ce qui n'est pas clair dans le code, c'est pourquoi vous avez fait quelque chose. Si vous adoptez une approche qui pourrait ne pas être évidente pour les autres, vous devriez avoir un commentaire qui explique pourquoi vous avez pris les décisions que vous avez prises. Je soupçonne que vous pourriez même ne pas réaliser qu'un commentaire est nécessaire avant quelque chose comme une révision de code, où les gens veulent savoir pourquoi vous avez fait X au lieu de Y - vous pouvez capturer votre réponse dans le code pour tous les autres qui le regardent A l'avenir.
La chose la plus importante, cependant, est de changer vos commentaires lorsque vous changez votre code. Si vous modifiez un algorithme, assurez-vous de mettre à jour les commentaires en expliquant pourquoi vous avez opté pour l'algorithme X sur Y. Les commentaires périmés sont une odeur de code encore plus grande.
C'est particulièrement irritant d'entendre en ce moment, j'ai passé du temps ce week-end à regarder du code très bien nommé, très propre et non commenté implémentant un algorithme de recherche (qui n'est pas réellement publié). Je le connais de haut niveau, le gars assis à côté de moi était l'inventeur et le code a été écrit il y a quelques années par quelqu'un d'autre. Nous pourrions à peine le suivre.
Votre collègue n'est pas assez expérimenté, évidemment.
Les commentaires doivent expliquer pourquoi, pas comment.
How les commentaires de type sont généralement mieux traités en utilisant le refactoring. Personnellement, j'évite généralement les commentaires en faveur de la refactorisation.
Avant:
# convert to cents
a = x * 100
# avg cents per customer
avg = a / n
# add to list
avgs < avg
t += 1
après:
total_cents = total * 100
average_per_customer = total_cents / customer_count
track_average(average_per_customer)
Je déclare votre collègue hérétique! Où sont mes bottes à brûlure hérétique?
Les commentaires obsessionnels sont mauvais et un mal de tête de maintenance, et les commentaires ne remplacent pas les méthodes, les classes, les variables bien nommées, etc. pourquoi quelque chose est comme ça peut être extrêmement précieux pour le pauvre idiot qui doit maintenir le code en six mois - en particulier lorsque ce pauvre idiot finit par être vous.
Quelques commentaires réels du code sur lequel je travaille:
// If this happens, somebody's been screwing around with the database definitions and
// has removed the restriction that a given alarm may have only one entry in the
// notifications table. Bad maintenance programmer! Bad! No biscuit!
// If an alert is active on our side but inactive on theirs, that might mean
// they closed the alert. (Or that we just haven't told them about it yet.) The
// logic comes later; for now, we'll just compile it in a list.
// If we know for a fact that an alarm isn't getting through, we're going to whine pretty
// aggressively about it until it gets fixed.
Idéalement, le code devrait être si bien codé qu'il devrait être auto-explicatif. Dans le monde réel, nous savons que le code de très haute qualité doit parfois être commenté.
Ce que vous devez absolument éviter, c'est la "redondance du code de commentaire" (commentaires qui n'ajoutent rien au code):
i++; // Increment i by 1
Ensuite, si la conception et la documentation du code sont bonnes (et maintenues/alignées), les commentaires sont encore moins utiles.
Mais dans certaines circonstances, les commentaires peuvent être une bonne aide pour la lisibilité du code:
while( foo )
{
if( dummy )
{
}
else // !dummy
{
}
} // end while( foo )
N'oubliez pas que vous devez également maintenir et synchroniser les commentaires ... les commentaires obsolètes ou erronés peuvent être une douleur terrible! Et, en règle générale, commenter trop peut être un symptôme d'une mauvaise programmation.
Définir catégoriquement une méthode ou un processus comme une "odeur de code" est une "odeur de fanatique". Le terme devient le nouveau "considéré comme nuisible".
N'oubliez pas que toutes ces sortes de choses sont censées être des lignes directrices.
Bon nombre des autres réponses donnent de bons conseils quant au moment où les commentaires sont justifiés.
Personnellement, j'utilise très peu de commentaires. Expliquez le but des processus non évidents et laissez la menace de mort occasionnelle à toute personne qui pourrait envisager de modifier par elle-même des choses qui nécessitaient des semaines de réglage.
Refactoriser tout jusqu'à ce qu'un jardin d'enfants puisse comprendre que ce n'est probablement pas une utilisation efficace de votre temps, et ne fonctionnera probablement pas aussi bien qu'une version plus concise.
Les commentaires n'affectent pas le temps d'exécution, donc le seul problème négatif à prendre en compte est la maintenance.
Le problème principal ici est la signification du terme "odeur de code".
Beaucoup de gens (y compris vous, je pense) comprennent qu'une odeur de code est quelque chose proche d'une erreur ou au moins quelque chose qui doit être corrigé. Vous le considérez peut-être comme un synonyme de "anti-pattern".
Ce n'est pas le sens du terme!
La métaphore de l'odeur de code provient de Wards Wiki , et ils soulignent:
Notez qu'un CodeSmell est un indice que quelque chose pourrait mal, pas une certitude. Un idiome parfaitement bon peut être considéré comme un CodeSmell car il est souvent mal utilisé ou parce qu'il existe une alternative plus simple qui fonctionne dans la plupart des cas. Appeler quelque chose comme CodeSmell n'est pas une attaque; c'est simplement un signe qu'un examen plus approfondi est justifié.
Alors, qu'est-ce que cela signifie que les commentaires sont une odeur de code: cela signifie que lorsque vous voyez un commentaire, vous devez faire une pause et penser: "Hmmm, je sens un indice que quelque chose pourrait être amélioré". Peut-être que vous pouvez renommer une variable, effectuer la "méthode d'extraction" - refactorisation - ou peut-être que le commentaire est en fait la meilleure solution.
C'est ce que cela signifie pour les commentaires d'être des odeurs de code.
EDIT: Je viens de tomber sur ces deux articles, ce qui l'explique mieux que moi:
Dans certains cas, aucune bonne dénomination, refactorisation, etc. ne peut remplacer un commentaire. Regardez cet exemple du monde réel (la langue est Groovy):
response.contentType="text/html"
render '{"success":true}'
Ça a l'air étrange, non? Probablement une erreur de copier-coller? Pleure un bug?
Maintenant la même chose avec des commentaires:
// DO NOT TOUCH THE FOLLOWING TWO LINES; the ExtJS UploadForm requires it exactly like that!!!
response.contentType="text/html" // must be text/html so the browser renders the response within the invisible iframe, where ExtJS can access it
render '{"success":true}' // ExtJS expects that, otherwise it will call the failure handler instead of the succss handler
Je pense que la règle est assez simple: imaginez un parfait inconnu voir votre code. Vous serez probablement étranger à votre propre code dans 5 ans. Essayez de minimiser l'effort mental pour comprendre votre code pour cet étranger.
Une bonne idée d'avoir les bons commentaires est de commencer par écrire des commentaires.
// This function will do something with the parameters,
// the parameters should be good according to some rules.
myFunction(parameters)
{
// It will do some things to get started.
// It will do more with the stuff.
// It will end doing things with the stuff.
}
Cela vous permet d'extraire facilement des méthodes pour même vous débarrasser des commentaires,
laissez simplement le code dire ces choses! Voyez comment cela est réécrit (couper/coller) d'une manière très agréable:
// This function will do something with the parameters,
// the parameters should be good according to some rules.
myfunction(parameters)
{
var someThing = initializedWithSomething;
doSomethingWith(someThing);
doMoreWith(someThing);
endDoingThingsWith(someThing);
return someThing;
}
// This function will do some things to get started,
// the parameters should be good according to some rules.
doSomethingWith(parameters)
{
parameters.manipulateInSomeWay();
... etc ...
}
... etc ...
Pour les choses qui ne peuvent pas être séparées, n'extrayez pas les méthodes et tapez le code sous les commentaires.
C'est ce que je considère comme un moyen utile de minimiser les commentaires, il est vraiment inutile d'aller commenter chaque ligne ... Ne documentez une seule ligne que s'il s'agit d'une initialisation de valeur magique ou lorsque cela a du sens.
Si les paramètres sont trop utilisés, ils doivent être des membres privés de votre classe.
Je pense que la réponse est celle habituelle "Cela dépend". Commenter le code juste pour commenter le code est une odeur. Commenter le code parce que vous utilisez un algorithme obscur qui est un ordre de grandeur plus rapide économise au programmeur de maintenance (généralement moi 6 mois après l'avoir écrit) une demi-journée de fouille dans le code pour déterminer ce qu'il fait.
// Dear me in the future. Please, resolve this problem.
ou
// You think this code was written by somebody else.
// No, it wasn't. You ([some name]) did it.
Les commentaires de code ne sont certainement pas une "odeur de code". Cette croyance vient généralement du fait que les commentaires peuvent devenir obsolètes (obsolètes) et peuvent être difficiles à maintenir. Cependant, avoir de bons commentaires qui expliquent pourquoi le code fait quelque chose d'une certaine manière peut (et est généralement) important pour la maintenance.
De bons commentaires permettent de mieux comprendre ce que fait le code et, plus important encore, pourquoi il le fait d'une manière particulière. Les commentaires sont destinés à être lus par les programmeurs et doivent être clairs et précis. Un commentaire difficile à comprendre ou incorrect n'est pas mieux que de n'avoir eu aucun commentaire.
L'ajout de commentaires clairs et précis à votre code signifie que vous n'avez pas besoin de vous appuyer sur la mémoire pour comprendre le "quoi" et le "pourquoi" d'une section de code. C'est le plus important lorsque vous regardez ce code plus tard, ou quelqu'un d'autre doit regarder votre code. Parce que les commentaires font partie du contenu textuel de votre code, ils doivent suivre de bons principes d'écriture en plus d'être clairement écrits.
Pour écrire un bon commentaire, vous devez faire de votre mieux pour documenter le but du code (le pourquoi, pas le comment) et indiquer le raisonnement et la logique derrière le code aussi clairement que possible. Idéalement, les commentaires doivent être écrits en même temps que vous écrivez le code. Si vous attendez, vous ne reviendrez probablement pas les ajouter.
Sams vous enseigne Visual C # 2010 en 24 heures , pp 348-349.
Si le code a été écrit d'une manière particulière pour éviter un problème présent dans une bibliothèque (à la fois une bibliothèque tierce ou une bibliothèque fournie avec le compilateur), il est logique de le commenter.
Il est également judicieux de commenter le code qui devra être modifié dans les futures versions, ou lors de l'utilisation d'une nouvelle version d'une bibliothèque, ou lors du passage de PHP4 à PHP5, par exemple.
Même le livre le plus bien écrit a probablement une introduction et des titres de chapitre. Les commentaires dans un code bien documenté sont toujours utiles pour décrire des concepts de haut niveau et expliquer comment le code est organisé.
Une mention honorable est l'anti-modèle:
J'ai l'impression que parfois des préamplis de licence FLOSS sont fréquemment utilisés au lie de documentation de fichier. La GPL/BSDL fait un joli texte de remplissage, et après cela, vous voyez rarement tout autre bloc de commentaires.
Je ne suis pas d'accord avec l'idée que la rédaction de commentaires pour expliquer le code est mauvaise. Cela ignore complètement le fait que le code comporte des bogues. Il pourrait être clair ce que le code fait sans commentaires. Il est moins probable que le code soit supposé clair. Sans commentaires, comment savoir si les résultats sont incorrects ou s'ils sont mal utilisés?
Les commentaires doivent expliquer le intention du code, de sorte que s'il y a une erreur, quelqu'un lisant les commentaires + le code ait une chance de le trouver.
Je me retrouve généralement à écrire des commentaires en ligne avant J'écris le code. De cette façon, il est clair ce que j'essaie d'écrire du code à faire et réduit la perte dans un algorithme sans vraiment savoir ce que vous essayez de faire.
Je répondrai par une question à moi. Pouvez-vous trouver le bogue dans le code non commenté ci-dessous?
tl; dr: La prochaine personne à gérer votre code pourrait ne pas être aussi divine que vous.
[org 0x7c00]
main:
mov ah, 0x0e
mov bx, string
call strreverse
call print
stop:
jmp $
strreverse:
pusha
mov dx, bx
mov cx, 0
strreverse_Push:
mov al, [bx]
cmp al, 0
je strreverse_pop
Push ax
add bx, 1
add cx, 1
jmp strreverse_Push
strreverse_pop:
mov bx, dx
strreverse_pop_loop:
cmp cx, 0
je strreverse_end
pop ax
mov [bx], al
sub cx, 1
add bx, 1
jmp strreverse_pop_loop
strreverse_end:
popa
ret
print:
pusha
print_loop:
mov al, [bx]
cmp al, 1
je print_end
int 0x10
add bx, 1
jmp print_loop
print_end:
popa
ret
string:
db 'Boot up', 0
times 510 -( $ - $$ ) db 0
dw 0xaa55
Les commentaires qui sont insérés parce que quelqu'un pense qu'il est acceptable d'avoir 700 lignes dans une méthode sont une odeur.
Les commentaires qui sont là parce que vous savez que si vous ne mettez pas de commentaire, quelqu'un fera encore la même erreur est une odeur.
Commentaires ajoutés parce que certains outils d'analyse de code l'exigent également.
Les personnes qui ne jamais mettent un commentaire, ou écrivent même un peu d'aide pour d'autres développeurs, sont aussi une odeur. Je suis étonné de voir combien de personnes n'écriront rien, mais se retourneront et reconnaîtront qu'elles ne se souviennent pas de ce qu'elles ont fait il y a 3 mois. Je n'aime pas écrire des documents, mais j'aime devoir répéter encore et encore la même chose aux gens.
Vous devez garder un équilibre entre le code et les commentaires ... Habituellement, j'essaie d'ajouter des commentaires qui reprennent un bloc de code. Non pas parce que je ne serai pas en mesure de comprendre le code (enfin, cela aussi), mais parce que je peux lire plus rapidement mon propre code et localiser des sections spécifiques où se passent les choses importantes.
Quoi qu'il en soit, mes critères personnels sont "en cas de doute, commentez". Je préfère avoir une ligne redondante qu'une ligne complètement cryptée que je ne pourrai pas comprendre. Je peux toujours supprimer les commentaires sur une révision de code, après un certain temps (et je le fais généralement)
De plus, les commentaires sont assez utiles pour ajouter des "mises en garde" comme "Attention! Si le format de l'entrée n'est pas ASCII, ce code devra changer!"
Je pense que les commentaires de code commencent très mal dans la vie. Je ne sais pas à propos de ces jours, mais quand j'ai appris la programmation à l'école pour la première fois, j'ai eu des devoirs du type "Écrivez un programme qui imprime les chiffres de un à dix sur des lignes distinctes. Assurez-vous de commenter votre code." Vous seriez marqué si vous n'avez pas ajouté de commentaires, car commenter votre code est une BONNE CHOSE.
Mais que dire d'un processus aussi trivial? Vous finissez donc par écrire le classique
i++; // add one to the "i" counter.
juste pour obtenir une note décente et, si vous en avez, nous former instantanément une très faible opinion des commentaires de code.
Le commentaire de code n'est pas une BONNE CHOSE. C'est UNE CHOSE PARFOIS NÉCESSAIRE, et Thomas Owens dans la réponse du haut fournit une excellente explication des situations dans lesquelles c'est nécessaire. Cependant, ces situations surviennent rarement dans les devoirs de type devoirs.
À bien des égards, l'ajout d'un commentaire doit être considéré comme un choix de dernier recours, lorsque ce qui doit être dit ne peut pas être dit clairement dans les parties actives du langage de programmation. Bien que la dénomination des objets puisse devenir obsolète, divers mécanismes de manque de rétroaction humains et informatiques permettent d'oublier facilement de conserver les commentaires et, par conséquent, les commentaires deviennent périmés beaucoup plus rapidement que le code actif. Pour cette raison, lorsqu'un choix est possible, la modification du code pour le rendre plus clair doit toujours être préférée à l'annotation de code peu clair avec des commentaires.
En lisant ceci, je me souviens d'une chose que j'ai lue pour la première fois (à partir d'une liste plus longue, conservée en prenant des photocopies) il y a quelques décennies:
Les vrais programmeurs n'écrivent pas de commentaires - s'il était difficile d'écrire, cela devrait être difficile à lire
Une odeur un peu plus ancienne me semble.
Bien sûr, les commentaires sont une odeur de code ...
chaque programmeur sait que nous finirons tous par devenir fous en raison de la quantité de travail, du débogage ou simplement de la folie que nous rencontrons.
"Faites ça!" dit votre chef de projet.
Vous répondez: "Cela ne peut pas être fait."
Ils disent: "Ensuite, nous trouverons quelqu'un d'autre pour le faire."
Vous dites: "D'accord, peut-être que cela peut être fait."
Et puis passez les X prochains jours .. semaines .. mois .. à essayer de le comprendre. Tout au long du processus, vous essaierez et échouerez, et vous échouerez. Nous le faisons tous. La vraie réponse est qu'il existe deux types de programmeurs, ceux qui commentent et ceux qui ne le font pas.
1) Ceux qui le font facilitent leur propre travail en documentant pour référence future, en commentant les routines échouées qui n'ont pas fonctionné (l'odeur ne les supprime pas après avoir trouvé celle qui fonctionne.), Ou en décomposant le code avec un commentaire le formatage en j'espère facilite la lecture ou la compréhension. Sérieusement, je ne peux pas leur en vouloir. Mais à la fin, ils se cassent et vous avez ceci: // dammit this code sucks! swear! curse! i hate it! i am going to write something here to vent my anger!!!!
2) Ceux qui ne prétendent pas être un super-héros ou vivent dans une grotte . Ils ont simplement un mépris insouciant pour les autres, eux-mêmes, et se moquent moins du code, ou de la signification qu'il pourrait éventuellement avoir pour plus tard.
Maintenant, ne vous méprenez pas .. les variables et les fonctions auto-documentées peuvent éviter cela complètement .. et croyez-moi vous ne pouvez jamais faire assez de nettoyage de code. Mais la simple vérité est que tant que vous conservez des sauvegardes, vous pouvez [~ # ~] toujours [~ # ~] supprimer les commentaires.
Il y a une grande différence fondamentale entre les commentaires et le code: les commentaires sont un moyen pour les gens de communiquer des idées à d'autres personnes, tandis que le code est principalement destiné à l'ordinateur. Il y a de nombreux aspects dans le "code" qui ne concernent que les humains, comme la dénomination et l'indentation. Mais les commentaires sont écrits strictement pour les humains, par les humains.
Par conséquent, écrire des commentaires est tout aussi difficile que toute communication humaine écrite! L'écrivain doit avoir une idée claire de qui est le public et du type de texte dont il aura besoin. Comment savoir qui lira vos commentaires dans dix, vingt ans? Et si la personne est d'une culture complètement différente? Etc. J'espère que tout le monde comprend cela.
Même à l'intérieur de la petite culture homogène dans laquelle je vis, il est tellement difficile de communiquer des idées à d'autres personnes. La communication humaine échoue généralement, sauf par accident.
Je dirais que ne pas utiliser certains commentaires dans votre code est une odeur de code. Bien que je convienne que le code devrait être auto-documenté autant que possible, vous atteignez un certain point où vous allez voir du code qui n'a aucun sens quelle que soit la façon dont le code est écrit. J'ai vu du code dans des applications commerciales où les commentaires sont à peu près obligatoires parce que:
- Vous devez faire quelque chose au cas par cas et il n'y a pas de bonne logique pour cela.
- Le code changera probablement dans un an ou deux lorsque les lois seront modifiées et que vous souhaitez le retrouver rapidement.
- Quelqu'un a modifié le code dans le passé parce qu'il ne comprenait pas ce que faisait le code.
De plus, les guides de style d'entreprise peuvent vous dire de faire quelque chose d'une certaine manière - s'ils disent que vous pourriez avoir des commentaires décrivant les blocs de code d'une fonction, alors incluez les commentaires.
Je dois être d'accord avec votre collègue. Je dis toujours que si je commente mon code, cela signifie que je crains que I ne puisse pas comprendre le mien code à l'avenir. C'est un mauvais signe.
La seule autre raison pour laquelle je saupoudre des commentaires dans le code est d'appeler quelque chose qui ne semble pas avoir de sens.
Ces commentaires prennent généralement la forme de quelque chose comme:
//xxx what the heck is this doing??
ou
// removed in version 2.0, but back for 2.1, now I'm taking out again
Voici ma règle générale:
- Écrivez le code et stockez un court résumé du code dans un document séparé.
- Laissez le code tranquille pendant plusieurs jours pour travailler sur autre chose.
- Revenez au code. Si vous ne pouvez pas immédiatement comprendre ce qu'il est censé faire, ajoutez le résumé au fichier source.
Informez votre collègue de la technique Programmation alphabétisée .
Les commentaires de code donnant, le cas échéant, des unités d'arguments de fonction et des retours, des champs de structure, même des variables locales peuvent être très utiles. N'oubliez pas le Mars Orbiter!
Non, les commentaires ne sont pas une odeur de code, ils sont juste un outil dont on peut abuser.
Exemples de commentaires bons:
// Je pense que c'est en cm. Une enquête plus approfondie est nécessaire!
// C'est une façon intelligente de faire X
// La liste est garantie d'être non vide ici
Cependant le code qui ne peut pas être compris du tout est beaucoup plus grand odeur de code…
Veuillez me donner du code propre pour travailler, cependant
si ce n'est pas une option, je préfère avoir un code "sale" avec des commentaires
que du code sale sans commentaires.
La plupart des mots ont été retirés de ma bouche. Mais je suppose que pour résumer le tout: le point des commentaires est de donner une description/explication de haut niveau de ce que fait le code.
De plus, voici quelques exemples d'utilisation des commentaires:
- comme en-têtes, pour indiquer l'objectif général d'une section de code
- de noter d'où j'ai codé le code et ainsi éviter le plagiat
- parfois à la fin des blocs, pour rappeler de quel bloc ils sont la fin
- pour indiquer que le code qui peut sembler suspect est ce qui est prévu (par exemple, ces moments étranges où un boîtier de commutation tombe)
- pour expliquer les mathématiques derrière un algorithme
Personne n'a dit cela jusqu'à présent dans ce fil, donc je vais:
Les noms de type, les noms de variable, les noms de fonction, les noms de méthode et les commentaires ne sont que des métadonnées sur votre code, et n'ont rien à voir avec le code machine que le compilateur génère (sauf les noms des symboles exportés et de débogage bien sûr).
Les noms de type et les noms de variable sont vos noms, les noms de fonction et de méthode sont vos verbes, avec ceux-ci vous décrivez les étapes à suivre. Les commentaires sont pour tout le reste.
Quelques exemples:
double temperature; // In Kelvins.
/**
* Returns true if ray hits the triangle
*/
bool castRayOnTriangle(Triangle t, Ray r)
{
//...
if (determinant == 0)
{
/* The ray and the triangle are parallel, no intersection possible.*/
return false;
}
//...
}
/* X algorithm. Visit http://en.wikipedia.org/... for details.*/
<implementation of something difficult to understand for the layman algorithm. >
Les commentaires peuvent devenir obsolètes s'ils ne sont pas mis à jour, mais les noms de variables et de fonctions peuvent également devenir obsolètes. J'ai récemment rencontré un champ bufPtr dans une structure C, qui n'a rien à voir avec les tampons ou les pointeurs. Et j'ai vu une fonction inflateBuffer qui ne décompresse pas une donnée dégonflée mais un fichier GZIP complet ... Ce sont aussi ennuyeux que des commentaires obsolètes.
Il ne semble pas que trop de réponses envisagent de programmer en équipe. Je suis un développeur senior et j'ai tendance à écrire des commentaires visant à expliquer ce qui est autrement simple à comprendre pour moi.
Je le vois comme une forme de communication ou d'éducation à titre posthume. J'encourage l'équipe à parcourir le code qu'elle utilise, mais elle n'a peut-être pas écrit pour mieux le comprendre.
Quelques exemples de cette semaine (code PHP):
//Pattern for finding jpeg photos
//Case insensitive pattern for jpg and jpeg
const PATTERN_PHOTO = "*.{[jJ][pP][gG],[jJ][pP][eE][gG]}";
J'espère que le nom PATTERN_PHOTO serait utile plus tard dans le code pour expliquer ce qu'il fait, mais sans les commentaires, comment serait-il clair pour un développeur junior ce que fait ce modèle spécifique?
Même jeu de code:
//Ignore . and .. directories in Linux
if($file != "." && $file != "..")
On s'attend à ce que nos développeurs connaissent PHP, mais pas qu'ils comprennent le système d'exploitation Linux que nous utilisons pour l'hébergement.
Donc, je trouve que ces commentaires augmentent réellement l'efficacité globale de notre équipe pour le très peu de temps qu'il faut pour les écrire.
- Il y a moins de cas de réécriture de code simplement parce qu'ils ne comprennent pas comment cela fonctionne. "Je ne comprenais pas comment il faisait ce qu'il était censé faire, alors je l'ai réparé." Sérieusement, j'ai dû faire face à cela auparavant.
- Il y a moins de questions posées sur des morceaux de code individuels. Répondre aux questions une seule fois, nécessite généralement de rechercher le code et le temps pour moi de me familiariser avec lui. Et parfois, je reçois la même question à plus d'une semaine d'intervalle. (Oui, ce serait sur des choses aussi simples que les exemples ci-dessus)
- Les autres développeurs sont encouragés et guidés à apprendre par eux-mêmes. Je m'attends à ce que s'ils tombent sur
//Ignore . and .. directories in Linuxils sauteraient probablement sur Google et comprendraient soudainement un peu mieux Linux.