En cours de redaction

Chapitre 4 - Commentaires

• qu’est qu’un code propres
• noms significatifs
• fonctions

Les commentaires sont, au mieux, un mal nécessaire

bien employés lorsqu’ils pallient notre incapacité à exprimer nos intentions par le code

les commentaires masquent toujours nos échecs

ressentez le poids de l’échec.

ils mentent

garder des commentaires à jour, pertinents et juste

La vérité doit se trouver uniquement dans le code

• Ne pas compenser le mauvais code par des commentaires

• S’expliquer dans le code

• Bons commentaires
• • Commentaires légaux
• • Commentaires informatifs
• • Expliquer les intentions, les raisons d’une décision
• • Clarifier
• • Avertir des conséquences désactiverions le cas de test à l’aide de l’attribut @Ignore et d’une chaîne d’explication appropriée, comme @Ignore(“Exécution trop longue”).
• • Commentaires TODO
• • Amplifier
• • Documentation Javadoc dans les API publiques
• Mauvais commentaires

béquilles ou d’excuses à du mauvais code

• • Marmonner Un commentaire qui nous oblige à consulter d’autres modules pour comprendre sa signification est un commentaire qui ne parvient pas à communique
• • Commentaires redondants
• • Commentaires trompeurs
• • Commentaires obligés
• • Commentaires de journalisation ———-> ca se fait encore ? Git?
• • Commentaires parasites
• • Bruit effrayant
• • Ne pas remplacer une fonction ou une variable par un commentaire
• • Marqueurs de position ——————-> private/public
• • Commentaires d’accolade fermante ——–> namespaces
• • Attributions et signatures ————–> ca se fait encore ? Git?
• • Mettre du code en commentaire ———–> WIP :)
• • Commentaires HTML
• • Information non locale
• • Trop d’informations
• • Lien non évident
• • En-têtes de fonctions
• • Documentation Javadoc dans du code non public

• questions

• importance du langage dans l’expressivite du code et donc la necessite d’ecrire des commentaires

• “Ne pas remplacer une fonction ou une variable par un commentaire” -> verbosite vs performances ? JIT/compilation?

• impact des outils recents sur les pratiques : gestionnaire de sources, doc generateur, outils de verification