En cours de redaction
- 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