No comment
Introduction
Longtemps considéré comme une bonne pratique, elle n'en est pas une.
"Ne commentez pas le mauvais code, récrivez-le" ( Brian W Kernighan et P.J. Plaugher)
Les commentaires ne sont pas nécessaires et il faut tout faire pour les éviter.
Pourquoi écrire un commentaire ?
Il y a peu de bonnes raisons d'écrire un commentaire.
Le problème du commentaire est qu'il a beaucoup d'inconvénients.
Le premier réflexe du développeur est de comprendre le code.
Il cherchera ensuite le commentaire ou de la documentation s'il n'arrive pas à le comprendre.
Et combien de fois êtes vous allez jusqu'à lire le commentaire pour vous apercevoir qu'il ne vous apprends rien de plus que ce que vous avez déjà compris dans le code.
Et je parle pas des fois où vous avez en plus dû essayer de comprendre le commentaire car faux, hors-sujet ou lui-même pas très claire.
Le développeur ne les lit pas et encore moins lorsque lui-même code. Il insère alors du code après le commentaire qui fait que le commentaire n'est plus au bon endroit, il peut également rendre un commentaire faux ou obsolète.
Il faut voir le commentaire comme un échec d'avoir un code compréhensible et expressif.
La bonne pratique est d'écrire un code expressif qui oblige le développeur à lire le code et à le comprendre directement. Il faut pour cela utiliser les bonnes pratiques de découpage et de nommage des méthodes.
Exemple de commentaires inutiles :
- Redondance: tout est dit
// on vérifie que l'utilisateur existe déjà if(object.getId() != null) { } - Explication du code qui va suivre : code trop complexe pour être compris par le développeur, où s'arrête la portée du commentaire.
- Commentaire obligatoire : souvent redondance avec le code
- Commentaire sur les attributs de classe :
- Commentaire incompréhensible lorsqu'on revient dessus (même lorsque c'est le notre)
Parfois les commentaires sont nécessaire
- javadoc public : description d'une fonction mis à la disposition des développeurs afin de lui éviter d'aller voir le code (lorsqu'il est accessible). On est tous en tant que développeur content d'avoir une javadoc sur une librairie afin de savoir précisément ce qu'on utilise (objectifs, limites,...).
- Code illogique pour un développeur mais qui est portée par le contexte métier (a voir pour l'implémenter différemment et l'isoler)
Bonne Pratique : Code Expresif vs Commentaires en Java
Introduction
L'une des bonnes pratiques en programmation Java est d'écrire du code expressif plutôt que de compter sur des commentaires pour expliquer ce que fait le code. Un code bien écrit doit être auto-documenté, c'est-à-dire que son intention et sa logique doivent être claires sans avoir besoin de commentaires supplémentaires.
Pourquoi préférer le code expressif aux commentaires ?
- Maintenabilité : Le code change plus souvent que les commentaires. Si vous devez mettre à jour la logique, il est facile d'oublier de mettre à jour les commentaires.
- Lisibilité : Un bon nom de variable ou de méthode peut souvent expliquer mieux qu'un long commentaire.
- Réduction du bruit : Les commentaires peuvent distraire et rendre le code plus difficile à lire.
Exemples
Mauvais exemple : Code avec des commentaires
// Calculer le prix total en ajoutant la TVA
public class CalculateurPrix {
public double calculerPrixTotal(double prix, double tauxTVA) {
// Ajouter la TVA au prix de base
double total = prix + (prix * tauxTVA);
return total;
}
}
// Utilisation du calculateur de prix pour un produit à 100 euros avec une TVA de 20%
CalculateurPrix calculateur = new CalculateurPrix();
double total = calculateur.calculerPrixTotal(100, 0.20);
Meilleur exemple : Code expressif sans commentaires
public class CalculateurTVA {
public double calculerTotalAvecTVA(double prixBase, double tauxTVA) {
return prixBase + (prixBase * tauxTVA);
}
}
// Utilisation du calculateur de taxes pour un produit à 100 euros avec une TVA de 20%
CalculateurTVA calculateur = new CalculateurTVA();
double totalPrix = calculateur.calculerTotalAvecTVA(100, 0.20);
Techniques pour écrire du code expressif en Java
1. Noms significatifs
Utilisez des noms de variables et de méthodes qui décrivent clairement leur rôle.
Avant :
public class TraitementCommande {
public double traiter(double x, double y) {
return x + (x * y);
}
}
// Utilisation
TraitementCommande traitement = new TraitementCommande();
double resultat = traitement.traiter(100, 0.20);
Après :
public class CalculateurTVA {
public double calculerTotalAvecTVA(double prixBase, double tauxTVA) {
return prixBase + (prixBase * tauxTVA);
}
}
// Utilisation
CalculateurTVA calculateur = new CalculateurTVA();
double totalPrix = calculateur.calculerTotalAvecTVA(100, 0.20);
2. Méthodes petites et spécialisées
Divisez votre code en petites méthodes qui font une seule chose.
Avant :
public class TraitementCommande {
public double traiterCommande(Map<String, Object> commande) {
// Calculer le prix total
double sousTotal = (double) commande.get("quantite") * (double) commande.get("prixUnitaire");
double tax = sousTotal * 0.20;
double total = sousTotal + tax;
// Appliquer la réduction si nécessaire
if (commande.containsKey("remise")) {
total -= (double) commande.get("remise");
}
return total;
}
}
Après :
public class TraitementCommande {
private double calculerSousTotal(Map<String, Object> commande) {
return (double) commande.get("quantite") * (double) commande.get("prixUnitaire");
}
private double appliquerTVA(double sousTotal, double tauxTVA) {
return sousTotal * tauxTVA;
}
private double appliquerRemise(double total, Map<String, Object> commande) {
if (commande.containsKey("remise")) {
return total - (double) commande.get("remise");
}
return total;
}
public double traiterCommande(Map<String, Object> commande, double tauxTVA) {
double sousTotal = calculerSousTotal(commande);
double tax = appliquerTVA(sousTotal, tauxTVA);
double total = sousTotal + tax;
return appliquerRemise(total, commande);
}
}
3. Utilisation de constantes pour les valeurs magiques
Avant :
public class CalculateurPrix {
public double calculerTotal(double prix) {
// 0.20 est le taux de TVA
return prix + (prix * 0.20);
}
}
Après :
public class CalculateurTVA {
private static final double TAUX_TVA_STANDARD = 0.20;
public double calculerTotalAvecTVA(double prixBase, double tauxTVA) {
return prixBase + (prixBase * tauxTVA);
}
// Méthode par défaut utilisant le taux de TVA standard
public double calculerTotalAvecTauxStandard(double prixBase) {
return calculerTotalAvecTVA(prixBase, TAUX_TVA_STANDARD);
}
}
4. Utilisation d'énumérations pour les valeurs constantes
Avant :
public class CalculateurRemise {
public double appliquerRemise(double total, int typeRemise) {
if (typeRemise == 1) {
return total * 0.95; // 5% de réduction
} else if (typeRemise == 2) {
return total * 0.90; // 10% de réduction
}
return total;
}
}
:::
Après :
public enum TypeRemise {
AUCUNE(1.0),
CINQ_POURCENT(0.95),
DIX_POURCENT(0.90);
private final double multiplicateur;
TypeRemise(double multiplicateur) {
this.multiplicateur = multiplicateur;
}
public double getMultiplicateur() {
return multiplicateur;
}
}
public class CalculateurRemise {
public double appliquerRemise(double total, TypeRemise typeRemise) {
return total * typeRemise.getMultiplicateur();
}
}
Conclusion
Écrire du code expressif en Java nécessite de prêter attention aux noms que vous choisissez pour vos variables et méthodes, de structurer votre code en petites unités logiques, et d'utiliser des constantes et énumérations pour les valeurs qui apparaissent fréquemment. En suivant ces bonnes pratiques, vous pouvez créer un code qui est non seulement plus facile à lire et à maintenir, mais aussi moins sujet aux erreurs introduites par des commentaires obsolètes ou incorrects.