Les commentaires sont-ils considérés comme une forme de documentation?

Lorsque j'écris de petits scripts pour moi-même, j'empile mon code avec des commentaires (parfois je commente plus que je code). Beaucoup de gens à qui je parle disent que je devrais documenter ces scripts, même s'ils sont personnels, de sorte que si je les vendais, je serais prêt. Mais les commentaires ne sont-ils pas une forme de documentation?

N'est-ce pas:

$foo = "bar"; # this is a comment
print $foo; # this prints "bar"

être considéré comme de la documentation, surtout si un développeur utilise mon code? Ou la documentation est-elle considérée comme étant en dehors du code lui-même?

Les commentaires sont définitivement de la documentation. Pour la plupart des projets, les commentaires sont (malheureusement) la principale (sinon la seule) forme de documentation du projet. Pour cette raison, il est très important de bien faire les choses. Vous devez vous assurer que cette documentation reste exacte malgré les modifications de code. Il s'agit d'un problème courant avec les commentaires. Les développeurs les «désaccordent» souvent lorsqu'ils travaillent dans du code familier, ils oublient donc de mettre à jour les commentaires pour refléter le code. Cela peut créer des commentaires obsolètes et trompeurs.

Beaucoup de gens suggèrent de rendre le code auto-documenté. Cela signifie qu'au lieu de commentaires, vous restructurez votre code pour en supprimer le besoin. Cela peut éliminer la plupart des commentaires "quoi" et "comment", mais n'aide pas vraiment avec les commentaires "pourquoi". Bien que cela puisse fonctionner efficacement pour se débarrasser de la plupart des commentaires, il existe encore de nombreuses fois où l'écriture d'un commentaire est le moyen le plus simple et le plus efficace de documenter un morceau de code.

Ils sont une forme de documentation, mais n'oubliez pas que la documentation est dans l'œil du spectateur ...

• Pour certains, un code auto-documenté suffit. Mais cela suppose un niveau de détail technique en tant que client. Nous devons être prudents en pensant que cela suffit, car notre ego peut nous dire "C'est évident ce que fait ce code" mais le temps peut prouver le contraire. Cela suppose également que vous connaissiez à l'avance les compétences du lecteur.

• Pour ceux qui regardent le code source mais avec moins d'expertise technique, les commentaires pourraient être corrects. Mais cela suppose que quelqu'un regarde le code source.

• Si vous êtes technique, mais que vous n'avez pas le temps de lire tout le code source, un manuel technique pourrait être ce qui est nécessaire.

• Et si l'utilisateur n'a pas de compétences techniques, mais a juste besoin de savoir ce qui se passe, la documentation utilisateur est ce qu'il faut.

La vraie question est donc qui est votre client? Si vous l'êtes, alors le code ou les commentaires auto-documentés suffisent. Si c'est pour quelqu'un d'autre, vous voudrez peut-être élargir la façon dont vous documentez.

Oui, les commentaires sont une forme de documentation. Qu'il s'agisse ou non d' une documentation utile pour quelqu'un qui doit maintenir ou mettre à jour votre code est une question ouverte.

Je sais que tu le pensais comme un exemple jetable, mais des trucs comme

print $foo; # this prints "bar"

n'est pas utile; il ajoute juste un fouillis visuel. Ne documentez pas l'évidence.

Les commentaires de bloc en tête d'une définition de méthode ou de fonction qui décrivent le but de la fonction ou de la méthode (en termes de haut niveau ), les entrées, les sorties, la valeur de retour (le cas échéant), les exceptions (le cas échéant), les conditions préalables et les postconditions sont utiles, mais seulement dans la mesure où ils indiquent à quelqu'un comment la fonction ou la méthode est censée être utilisée. Ils n'expliquent pas pourquoi la fonction existe.

Si quelqu'un d'autre a besoin de maintenir votre code, vous devez documenter les exigences et la conception quelque part, et cela n'est généralement pas fait dans le code source lui-même.

Je trouve que s'en tenir à l'approche de Bob Martin à ce sujet, de Clean Code, résout généralement le problème de savoir si vous pensez que vous êtes en train de commenter ou de commenter et de laisser de la documentation:

Nous sommes auteurs. Et une chose au sujet des auteurs, c'est qu'ils ont des lecteurs. En effet, les auteurs sont responsables de bien communiquer avec leurs lecteurs. La prochaine fois que vous écrivez une ligne de code, souvenez-vous que vous êtes un auteur, écrivant pour des lecteurs qui jugeront de vos efforts.

... le rapport entre le temps passé à lire et à écrire est bien supérieur à 10: 1. Nous lisons constamment l'ancien code dans le cadre de l'effort d'écriture de nouveau code.

En d'autres termes, votre code est-il explicite sans la documentation? Il n'y a pas de règle définie (sauf si vous travaillez pour quelqu'un comme Microsoft dont la documentation est accessible au public), il s'agit principalement d'aider le futur lecteur du code qui est souvent vous.

La documentation doit documenter le pourquoi pas le comment . Le comment devrait être évident dans le code, c'est-à-dire à moins qu'il ne s'agisse d'une astuce d'optimisation obscure ou d'une autre technique spécifique au langage qui ne se produit pas couramment.

Le Why ne devrait probablement pas être dans le code, il devrait être ailleurs comme un backlog de produit, qui est lié pour valider les commentaires avec des identifiants d'histoire qui peuvent être recherchés dans un journal des modifications ou un nom de branche.

Les commentaires sont une forme de documentation. Une forme inférieure et qui suggère que vous avez localisé une zone de votre code qui peut être mieux prise en compte.

Il semble que vous commentiez les choses de manière compulsive. Avoir d'autres options peut être une bonne chose. Je peux penser à trois formes supérieures de documentation:

1) Factorisez mieux votre code. Au lieu d'ajouter un commentaire, extrayez une méthode ou une fonction dont le nom est le texte du commentaire que vous étiez sur le point d'écrire. Le code indique donc ce que votre commentaire était sur le point de dire.

2) Tests. C'est la forme de documentation que je recherche habituellement. Les tests unitaires et les tests d'acceptation sont une documentation évolutive et peuvent être lus facilement si de nombreuses méthodes significatives sont utilisées pour exprimer l'intention, comme au point 1.

3) Pour les scripts, l'option --help. C'est là que vous pouvez devenir fou sur doc. Conservez des exemples, anticipez les besoins de l'utilisateur.

En résumé, si vous êtes enclin à coller un commentaire, vérifiez s'il existe un moyen de communiquer avec le lecteur en structurant mieux le code. Ou existe-t-il un test qui communique pourquoi ce code existe? Si vous avez toujours envie de le commenter, admettez la défaite et faites-le.