Comment aimez-vous vos commentaires? [fermé]
https://stackoverflow.com/questions/121945
-
02-07-2019 - |
italiano
english
français
española
中国
日本の
العربية
Deutsch
한국어
Português
RussianQuestion
Quelles sont vos meilleures pratiques pour les commentaires? Quand doivent-ils être utilisés et que contiennent-ils? Ou est-ce que des commentaires sont même nécessaires?
La solution
Les commentaires sont essentiels pour la maintenabilité. Le point le plus important à retenir est d'expliquer POURQUOI que vous faites quelque chose et non CE QUE vous faites.
Autres conseils
À l’école, la règle était de tout commenter, si bien que les commentaires l'emportaient sur le code. Je pense que c'est idiot.
Je pense que les commentaires devraient être utilisés pour documenter le " pourquoi " derrière le code, pas le "comment" ... le code lui-même explique le "comment". S'il y a une opération qui ne explique pas vraiment pourquoi c'est fait, c'est un bon endroit pour un commentaire.
Les TODO et les FIXME sont parfois commentés, mais ils devraient idéalement figurer dans vos outils de gestion de code source et de suivi des bogues.
La seule exception pour laquelle les commentaires apparemment inutiles ne me dérangent pas concerne les générateurs de documentation, qui n'imprimeront la documentation que pour les fonctions commentées. Dans ce cas, chaque classe publique et interface API doit être commentée au moins pour obtenir la documentation générée.
Idéalement, votre programme peut communiquer avec le lecteur sous forme de code et non de commentaire. La capacité d'écrire un logiciel que les autres programmeurs peuvent comprendre rapidement sépare les meilleurs programmeurs de la moyenne à mon avis. En règle générale, si vous ou vos collègues ne pouvez pas comprendre une section de code sans commentaires, il s’agit d’un " odeur de code " et la refactorisation devrait être en ordre. Cependant, il y aura des bibliothèques archaïques ou une autre intégration que quelques commentaires pour guider le développeur moyen ne sont pas nécessairement mauvais.
Comme souvent, la réponse est: cela dépend. Je pense que la raison pour laquelle vous avez écrit un commentaire est très importante pour la décision, que le commentaire soit bon ou mauvais. Les commentaires peuvent être motivés par plusieurs raisons:
- pour rendre la structure plus claire (c'est-à-dire quelle boucle se termine ici)
Mauvais: , cela ressemble à une odeur de code possible. Pourquoi le code est-il si compliqué qu'il a besoin d'un commentaire pour le clarifier?
- expliquer ce que fait le code
Très mauvais: c'est à mon avis dangereux. Il arrive souvent que vous changiez le code plus tard et oubliez le commentaire. Maintenant le commentaire est faux. C'est très mauvais.
- pour indiquer une solution de contournement / un correctif
Bien: Parfois, la solution d'un problème semble claire, mais l'approche simple pose problème. Si vous résolvez le problème, il peut être utile d'ajouter un commentaire expliquant pourquoi cette approche a été choisie. Sinon, un autre programmeur peut penser plus tard qu’il «optimise» le code et réintroduit le bogue. Pensez au problème Debian OpenSSL. Les développeurs Debian ont supprimé une variable unitialisée. Normalement, une variable unitaire est un problème, dans ce cas, elle était nécessaire pour le caractère aléatoire. Un commentaire de code aurait aidé à clarifier cela.
- à des fins de documentation
Bon : vous pouvez générer de la documentation à partir de commentaires spéciaux (par exemple, Javadoc). Il est utile de documenter les API publiques, ce qui est indispensable. Il est important de se rappeler que la documentation contient l'intention du code, pas l'implémentation. Alors répond au commentaire de la question "Pourquoi avez-vous besoin de la méthode (et comment l’utilisez-vous)" ou Que fait la méthode?
Je pense que le nouveau mouvement pour supprimer les commentaires est mauvais ... la raison, beaucoup de programmeurs pensent écrire un code facile à comprendre et ne nécessitant pas de commentaires. Mais en réalité, ce n’est tout simplement pas le cas.
Quel pourcentage du code des autres peuples lisez-vous et comprenez-vous instantanément .. Peut-être que je lis trop d'asp, de Perl et de C ++ classiques, mais la plupart des choses que je lis sont difficiles à parcourir.
Avez-vous déjà lu le code de quelqu'un et en avez-vous été complètement dérouté? Pensez-vous qu'ils pensaient pendant qu'ils écrivaient, c'est de la merde mais je m'en fiche. Ils ont probablement pensé: oh… c’est très intelligent et ce sera SUPER rapide.
Juste quelques remarques:
Les commentaires sont importants pour tout ce qui ne peut pas être facilement déduit du code (par exemple, des algorithmes mathématiques complexes).
Le problème avec les commentaires est qu’ils doivent être conservés comme le code mais ne le sont souvent pas du tout.
Je n'aime pas les commentaires comme celui-ci:
// Create the "Analyze" button
Button analyzeButton = new Button();
analyzeButton.Text = "Analyze";
analyzeButton.Location = new Point( 100, 100 );
Controls.Add( analyzeButton );
Mieux:
CreateAnalyzeButton();
void CreateAnalyzeButton()
{
Button analyzeButton = new Button();
analyzeButton.Text = "Analyze";
analyzeButton.Location = new Point( 100, 100 );
Controls.Add( analyzeButton );
}
Le code raconte maintenant toute l'histoire. Pas besoin de commentaire.
Je pense que cela dépend du scénario.
Les méthodes / fonctions / classes ont besoin d’une brève description de ce qu’elles font, de la façon dont elles le font, de ce qu’elles prennent et de ce qu’elles retournent, si elles ne sont pas immédiatement évidentes et qui (comme dans mon code) se présente généralement sous la forme d’un javadoc- bloc de commentaires de style.
Code de bloc, j'ai tendance à laisser un commentaire au-dessus d'un bloc de lignes pour expliquer son rôle ou un commentaire en fin de ligne s'il s'agit d'un appel de fonction bref et cryptique.
Utilisez la recherche de balises et vous découvrirez que SO a déjà beaucoup de discussions sur les commentaires de code:
Consultez Code complet . C'est tout simplement le meilleur choix pour de tels sujets.
