Le chapitre 2 de "Clean Code" est probablement l'un des plus importants car il traite des noms que nous donnons à nos variables, fonctions, classes et autres éléments de code. Pour un développeur React et TypeScript, choisir des noms appropriés est encore plus crucial car la lisibilité et la maintenabilité du code en dépendent directement. Voyons comment appliquer ces principes fondamentaux pour améliorer significativement la qualité de votre code.
Points essentiels à retenir:
- Les bons noms sont auto-documentés et réduisent le besoin de commentaires
- Un nom doit révéler l'intention, pas masquer l'information
- Les noms doivent être prononçables et recherchables facilement
- Les conventions de nommage doivent être constantes dans tout le code
- En TypeScript et React, des noms bien choisis renforcent le typage et la structure des composants
1. Les principes fondamentaux du nommage
Selon Robert C. Martin, choisir des noms appropriés est l'une des compétences les plus sous-estimées en programmation. Un bon nom peut vous faire gagner des heures de débogage et rendre votre code immédiatement plus clair pour vos collègues et votre futur vous-même.
Révéler l'intention
Un nom doit révéler pourquoi une variable, fonction ou classe existe, ce qu'elle fait et comment elle est utilisée. Si un nom nécessite un commentaire pour être compris, c'est qu'il ne révèle pas suffisamment son intention.
Exemples de noms qui ne révèlent pas leur intention vs. ceux qui la révèlent
// Mauvais: Noms qui ne révèlent pas l'intention const d = 5; // Durée en jours const fn = (u) => api.getData(u); // Récupère les données de l'utilisateur const arr = users.filter(u => u.active); // Liste des utilisateurs actifs // Bon: Noms qui révèlent clairement l'intention const durationInDays = 5; const fetchUserData = (userId) => api.getData(userId); const activeUsers = users.filter(user => user.active);
Éviter la désinformation
Évitez les noms qui peuvent induire en erreur ou suggérer des choses incorrectes. Par exemple, n'appelez pas une collection de comptes accountList si ce n'est pas techniquement une liste mais plutôt un ensemble ou un tableau. Préférez accounts ou accountGroup.
Exemples de noms trompeurs vs. précis
// Trompeur
const productList = {apple: {price: 1}, banana: {price: 2}}; // Ce n'est pas une liste mais un objet!
// Précis
const productMapping = {apple: {price: 1}, banana: {price: 2}};
// ou simplement
const products = {apple: {price: 1}, banana: {price: 2}};
// Trompeur en React
const ProductListItem = ({ product }) => { // Mais traite un seul produit, pas une liste!
return <div>{product.name}</div>;
};
// Précis en React
const ProductItem = ({ product }) => {
return <div>{product.name}</div>;
};
2. Techniques de nommage en React et TypeScript
L'utilisation de React et TypeScript amplifie l'importance des bons noms. La combinaison de composants, hooks, types et interfaces rend essentielle l'application stricte des principes de nommage pour maintenir un code lisible et évolutif.
Nommer les composants React
Les composants React suivent la convention PascalCase et doivent être nommés selon leur responsabilité principale. Un bon nom de composant décrit ce qu'il rend à l'écran ou quelle fonctionnalité il encapsule.
Exemples de nommage de composants React
// Mauvais: nom trop générique, pas descriptif
const Display = () => {
return <div>Some product information</div>;
};
// Bon: nom descriptif qui indique clairement ce que fait le composant
const ProductDetailsCard = () => {
return <div>Some product information</div>;
};
// Mauvais: nom qui ne reflète pas la responsabilité
const HandleClick = ({ onClick, children }) => {
return <button onClick={onClick}>{children}</button>;
};
// Bon: nom qui décrit le rôle du composant
const ActionButton = ({ onClick, children }) => {
return <button onClick={onClick}>{children}</button>;
};
Nommer les types et interfaces TypeScript
TypeScript permet de définir des types personnalisés qui renforcent la sécurité et la documentation de votre code. Un bon nom de type doit être substantif et décrire précisément les données qu'il représente.
Exemples de nommage de types et interfaces TypeScript
// Mauvais: nom générique, pas descriptif
interface Data {
id: string;
val: number;
desc: string;
}
// Bon: nom descriptif qui indique clairement ce que représente l'interface
interface ProductInventory {
productId: string;
quantity: number;
description: string;
}
// Mauvais: utilisation de préfixes inutiles
interface IUserData {
// 'I' préfixe est redondant
name: string;
age: number;
}
// Bon: nom clair sans préfixes inutiles
interface UserProfile {
name: string;
age: number;
}
// Bon: utilisation de suffixes pour les props de composants
interface ProductCardProps {
product: Product;
onSelect: (product: Product) => void;
isSelected: boolean;
}
Nommer les hooks personnalisés
Les hooks personnalisés en React doivent commencer par "use" et décrire l'action ou l'état qu'ils gèrent. Un bon nom de hook permet de comprendre immédiatement ce qu'il fait et comment l'utiliser.
Exemples de nommage de hooks personnalisés
// Mauvais: ne commence pas par "use", pas descriptif
const fetchData = (url) => {
const [data, setData] = useState(null);
const [loading, setLoading] = useState(false);
useEffect(() => {
// logique de récupération
}, [url]);
return { data, loading };
};
// Bon: commence par "use", nom descriptif
const useProductData = (productId) => {
const [product, setProduct] = useState(null);
const [isLoading, setIsLoading] = useState(false);
const [error, setError] = useState(null);
useEffect(() => {
// logique de récupération du produit
}, [productId]);
return { product, isLoading, error };
};
3. Erreurs courantes et comment les éviter
Même avec les meilleures intentions, certaines erreurs de nommage se glissent fréquemment dans notre code. Voici les plus communes et comment les éviter dans un environnement React/TypeScript.
Abréviations et noms courts
Les abréviations obscurcissent l'intention et rendent le code difficile à comprendre pour les nouveaux développeurs. Robert C. Martin recommande d'utiliser des noms complets et descriptifs, excepté dans des contextes très limités comme les variables de boucle.
Exemples d'abréviations à éviter vs. noms complets
// Mauvais: abréviations obscures
const usrPrm = {id: 1, fn: "John", ln: "Doe"};
const dispProdDet = (p) => {
console.log(`${p.pn}: $${p.pr}`);
};
// Bon: noms complets et descriptifs
const userParameters = {id: 1, firstName: "John", lastName: "Doe"};
const displayProductDetails = (product) => {
console.log(`${product.productName}: $${product.price}`);
};
// Exception acceptable pour les indices de boucle courtes
for (let i = 0; i < products.length; i++) {
// 'i' est acceptable ici car c'est une convention standard
}
// Mais pour les opérations plus complexes, utilisez des noms descriptifs
products.forEach((product, index) => {
// 'product' et 'index' sont plus clairs que 'p' et 'i'
});
Constance dans les conventions
La constance est primordiale dans les conventions de nommage. Si vous utilisez getUserData() pour une fonction, n'utilisez pas fetchClientInfo() pour une fonction similaire ailleurs. L'incohérence force le lecteur à mémoriser des mappages arbitraires.
Exemples d'incohérence vs. cohérence
// Incohérent: différentes conventions pour des concepts similaires
const getProductData = (id) => api.fetchProduct(id);
const fetchUserInfo = (id) => api.getUser(id);
const clientRetrieval = (id) => api.getClient(id);
// Cohérent: même convention pour des concepts similaires
const getProductData = (id) => api.fetchProduct(id);
const getUserData = (id) => api.getUser(id);
const getClientData = (id) => api.getClient(id);
// Incohérent en React: mélange de conventions pour les gestionnaires d'événements
const UserForm = () => {
const handleSubmit = () => { /* ... */ };
const nameChange = () => { /* ... */ };
const onPasswordUpdate = () => { /* ... */ };
return <form>...</form>;
};
// Cohérent en React: convention uniforme pour les gestionnaires d'événements
const UserForm = () => {
const handleSubmit = () => { /* ... */ };
const handleNameChange = () => { /* ... */ };
const handlePasswordUpdate = () => { /* ... */ };
return <form>...</form>;
};
Noms qui nécessitent un contexte
Évitez les noms qui nécessitent que le lecteur connaisse le contexte environnant pour comprendre leur signification. Les noms doivent être auto-suffisants autant que possible.
Exemples de noms dépendants du contexte vs. autonomes
// Mauvais: "name" et "value" sont générique et dépendent du contexte
function processData(data) {
const name = data.name;
const value = data.value;
return `${name}: ${value}`;
}
// Bon: noms qui se tiennent par eux-mêmes
function formatProductPrice(product) {
const productName = product.name;
const productPrice = product.price;
return `${productName}: $${productPrice}`;
}
// En TypeScript, le typage aide à clarifier le contexte
interface OrderItem {
productId: string;
quantity: number;
}
// Maintenant le nom est plus clair grâce au type
function calculateTotalPrice(items: OrderItem[]): number {
// Le typage clarifie ce que sont les "items"
return items.reduce((total, item) => {
// ...calcul
}, 0);
}
À Retenir
- Intention claire : Choisissez des noms qui révèlent pourquoi un élément existe, ce qu'il fait et comment il est utilisé.
- Évitez la désinformation : Ne donnez pas de noms qui peuvent induire en erreur sur le type ou la nature d'un élément.
- Noms prononçables : Si vous ne pouvez pas prononcer un nom, vous ne pourrez pas en discuter efficacement.
- Noms recherchables : Privilégiez des noms qui peuvent être facilement trouvés dans une recherche textuelle.
- Conventions de nommage : Suivez les conventions établies - PascalCase pour les composants React, camelCase pour les fonctions et variables, préfixe "use" pour les hooks.
- Constance : Utilisez les mêmes termes pour les mêmes concepts dans tout votre code.
- Noms significatifs en TypeScript : Profitez du typage fort pour renforcer la clarté de vos noms.