Il est intéressant de noter que la lisibilité appliquée au langage naturel se mesure à la vitesse de lecture et de compréhension. J'imagine qu'une règle simple peut en effet être adoptée, si un commentaire de code particulier n'améliore pas cette propriété, il peut être évité .
Pourquoi des commentaires?
Bien que le commentaire de code soit une forme de documentation intégrée, les langages de programmation haut de gamme peuvent éviter la programmation "sur-documentée" superflue (de code) en utilisant des éléments du langage lui-même. Il est également déconseillé de transformer le code en une liste à partir de textes de programmation où les déclarations individuelles sont littéralement expliquées de manière presque tautologique (gardez à l’esprit l’exemple "/ * incrémenté de 1 * /" dans les réponses déjà fournies), ce qui rend ces commentaires pertinents. aux programmeurs inexpérimentés avec la langue.
Néanmoins, l'intention est d'essayer de commenter le code "sous-documenté" (mais dénué de sens) qui est vraiment "la source de tout mal". L'existence même d'un code "sous-documenté" est un mauvais signal - qu'il s'agisse d'un gâchis non structuré ou d'un mot délirant à caractère mystique. De toute évidence, la valeur de ce code est au moins discutable. Malheureusement, il y a toujours des exemples, quand il est en effet préférable d'introduire un commentaire dans une section de lignes de code formatées (regroupés visuellement) plutôt que de l'envelopper dans un nouveau sous-programme (gardez à l'esprit la "consistance stupide" qui "est le lutin des petits esprits") .
Lisibilité du code! = Commentaires du code
Le code lisible ne nécessite pas d’annotations par commentaires. À chaque endroit particulier du code, il y a toujours un contexte de tâche que ce code particulier est censé réaliser. Si le but manque et / ou si le code fait quelque chose de mystérieux = évitez-le à tout prix. Ne laissez pas de hacks bizarres peupler votre code - c'est le résultat direct de la combinaison de technologies buggy et de manque de temps / d'intérêt pour comprendre les fondements. Évitez le code mystique dans votre projet!
D'autre part, Readable programme = code + documentation peut contenir plusieurs sections de commentaires légitimes, par exemple pour faciliter la génération de documentation "commentaires dans l'API".
Suivre les normes de style de code
Assez drôle, la question n'est pas de savoir pourquoi commenter du code, mais bien de travailler en équipe - comment produire du code dans un style hautement synchronisé (que tout le monde peut lire / comprendre). Suivez-vous des normes de style de code dans votre entreprise? Son objectif principal est d'éviter d'écrire du code qui nécessite une refactorisation, qui soit trop "personnel" et "subjectivement" ambigu. Donc, je suppose que si on voit la nécessité d’utiliser le style de code, il existe toute une série d’outils permettant de le mettre en œuvre correctement - en commençant par l’éducation des personnes et en terminant par l’automatisation pour le contrôle de la qualité du code (nombreuses notes, etc.) et (révision). systèmes de contrôle de code intégrés).
Devenir un évangéliste à la lisibilité du code
Si vous acceptez, ce code est lu plus souvent qu'il n'est écrit. Si une expression claire des idées et de la pensée sont clairement importantes pour vous, quelle que soit la langue utilisée pour communiquer (mathématiques, code machine ou ancien anglais) .. Si votre mission est d'éradiquer toute forme de pensée alternative terne et laide .. (désolé , le dernier provient d’un autre "manifeste") .. posez des questions, initiez des discussions, commencez à diffuser des livres stimulants sur le nettoyage de code (probablement non seulement quelque chose de similaire aux modèles de Beck, mais plus similaire à celui déjà mentionné par RC Martin ) qui aborde l’ambiguïté en programmation. Plus loin, passage d'idées clés (cité dans le livre de O'Reilly sur la lisibilité)
- Simplifiez l'attribution de nom, les commentaires et le formatage avec des astuces qui s'appliquent à chaque ligne de code.
- Affinez les boucles, la logique et les variables de votre programme pour réduire la complexité et la confusion
- Problèmes d'attaque au niveau de la fonction, tels que la réorganisation de blocs de code pour effectuer une tâche à la fois
- Écrivez un code de test efficace, complet et concis, ainsi que lisible
En coupant les "commentaires", il en reste encore beaucoup (j'imagine qu'écrire du code qui n'a pas besoin de commentaires est un excellent exercice!). Nommer des identificateurs sémantiquement significatifs est un bon début. Ensuite, structurez votre code en regroupant des opérations connectées logiquement en fonctions et en classes. Etc. Un meilleur programmeur est un meilleur écrivain (bien sûr, en supposant que d'autres compétences techniques soient données).