Chapitre 5 – Le Formatage

architecture

Clean Code de Robert C. Martin : Chapitre 5 - Le Formatage

Le formatage du code est souvent considéré comme un aspect superficiel de la programmation. Pourtant, comme l'explique Robert C. Martin dans le chapitre 5 de "Clean Code", la mise en forme du code est cruciale: "Quand les gens regardent sous le capot, nous voulons qu'ils soient impressionnés par la netteté, la cohérence et l'attention aux détails qu'ils perçoivent." Un formatage soigné communique le professionnalisme et l'attention portée à tous les aspects du projet, particulièrement dans un environnement de développement React et TypeScript où la clarté du code est essentielle.

Points essentiels à retenir:

  • Le formatage n'est pas qu'une question d'esthétique, mais une nécessité fondamentale pour la communication entre développeurs
  • Un code bien mis en forme est comme un journal bien structuré : les informations importantes en haut, les détails en dessous
  • La taille idéale d'un fichier est généralement entre 30 et 100 lignes, avec une limite maximale autour de 500 lignes
  • La largeur des lignes devrait être limitée (idéalement entre 25-50 caractères, maximum 120)
  • Les règles de formatage doivent être décidées en équipe et appliquées uniformément via des outils comme ESLint et Prettier
font-size="16" font-weight="bold" fill="#333">Formatage Vertical Métaphore du journal Espacement vertical Densité verticale Distance verticale Ordonnancement vertical Taille fichier: 30-100 lignes (max 500) Formatage Horizontal Ouverture et densité Alignement horizontal Indentation Portées fictives Taille ligne: 25-50 car. (max 100) Format défini par l'équipe et maintenu avec ESLint + Prettier

1. Le but du formatage

Robert C. Martin est catégorique : "Le formatage du code est important. Trop important pour être ignoré, et trop important pour être traité avec fanatisme." Le formatage n'est pas une simple question de préférences personnelles, mais un élément crucial de communication professionnelle. Pour un développeur React et TypeScript, un bon formatage peut faire la différence entre un code qui évolue facilement et un code qui devient rapidement une dette technique.

La communication avant tout

Martin le souligne clairement : "La communication est la première mission d'un développeur professionnel." Contrairement à ce que certains pourraient penser, "faire fonctionner le code" n'est pas la priorité numéro un. La fonctionnalité créée aujourd'hui changera probablement à la prochaine version, mais la lisibilité du code aura un impact profond sur toutes les modifications futures. Dans un projet React, où les composants sont constamment améliorés et réutilisés, cette lisibilité devient encore plus cruciale.

Temps investi vs. temps économisé

  • 30 minutes: Configuration initiale des outils de formatage (ESLint + Prettier)
  • 15 minutes: Discussion d'équipe sur les conventions
  • 5 minutes: Application automatique du formatage par développeur/jour
  • Économies: 1-2 heures/semaine/développeur en temps de lecture et compréhension du code

2. Formatage vertical

Le formatage vertical concerne l'organisation globale du fichier et la manière dont le code s'étend de haut en bas. Robert C. Martin analyse en détail les distributions de tailles de fichiers dans plusieurs projets majeurs (JUnit, FitNesse, Time and Money, etc.) et conclut qu'il est possible de construire des systèmes significatifs avec des fichiers d'environ 200 lignes en moyenne, avec une limite supérieure raisonnable de 500 lignes. Cette taille optimale s'applique parfaitement aux composants React modernes.

La métaphore du journal

Uncle Bob explique que les fichiers de code devraient être comme des articles de journal bien structurés. "En haut, vous vous attendez à un titre qui vous dira de quoi parle l'histoire... Le premier paragraphe vous donne un synopsis de toute l'histoire... En descendant, les détails augmentent jusqu'à ce que vous ayez toutes les dates, noms, citations et autres éléments." Cette métaphore s'applique parfaitement aux composants React modernes, où les imports, les interfaces TypeScript et les déclarations principales doivent apparaître en haut, suivis progressivement par les détails d'implémentation.

Structure verticale d'un composant React/TypeScript

// 1. Imports (regroupés par catégories)
import React, { useState, useEffect } from 'react';
import { useSelector } from 'react-redux';
import { UserData } from '../../types';
import { fetchUserData } from '../../api';

// 2. Types/Interfaces
interface UserProfileProps {
  userId: string;
  showDetails: boolean;
}

// 3. Composant principal
const UserProfile: React.FC<UserProfileProps> = ({ userId, showDetails }) => {
  // État et hooks
  const [userData, setUserData] = useState<UserData | null>(null);
  const theme = useSelector((state) => state.theme);
  
  // Effets
  useEffect(() => {
    const loadData = async () => {
      try {
        const data = await fetchUserData(userId);
        setUserData(data);
      } catch (error) {
        console.error('Failed to load user data', error);
      }
    };
    
    loadData();
  }, [userId]);
  
  // Fonctions auxiliaires
  const formatName = (user: UserData) => `${user.firstName} ${user.lastName}`;
  
  // Rendu conditionnel
  if (!userData) return <Spinner />;
  
  // Rendu principal
  return (
    <div className="user-profile">
      <h2>{formatName(userData)}</h2>
      {showDetails && <UserDetails data={userData} theme={theme} />}
    </div>
  );
};

// 4. Exports
export default UserProfile;
            

Espacement vertical entre concepts

Martin insiste sur l'importance des lignes vides pour séparer les concepts. Il présente une comparaison frappante du même code avec et sans lignes vides, montrant comment l'espacement vertical sert d'indice visuel qui identifie les nouveaux concepts. Dans les composants React, les espaces entre les déclarations d'imports, les définitions de types, les hooks, et les fonctions de rendu créent une structure visuelle immédiatement compréhensible.

Espacement vertical en React/TypeScript

// Avec espacement vertical approprié
import React, { useState, useEffect } from 'react';
import { useTheme } from '../hooks/useTheme';

interface UserCardProps {
  userId: string;
  showDetails: boolean;
}

const UserCard: React.FC<UserCardProps> = ({ userId, showDetails }) => {
  const [userData, setUserData] = useState<UserData | null>(null);
  const [isLoading, setIsLoading] = useState(true);
  
  const theme = useTheme();
  
  useEffect(() => {
    fetchUserData(userId)
      .then(data => setUserData(data))
      .finally(() => setIsLoading(false));
  }, [userId]);
  
  if (isLoading) return <Spinner />;
  
  return (
    <div className={theme.card}>
      {userData && <UserInfo user={userData} />}
      {showDetails && userData && <UserDetails user={userData} />}
    </div>
  );
};

export default UserCard;

// Sans espacement vertical (difficile à lire)
import React, { useState, useEffect } from 'react';
import { useTheme } from '../hooks/useTheme';
interface UserCardProps {
  userId: string;
  showDetails: boolean;
}
const UserCard: React.FC<UserCardProps> = ({ userId, showDetails }) => {
  const [userData, setUserData] = useState<UserData | null>(null);
  const [isLoading, setIsLoading] = useState(true);
  const theme = useTheme();
  useEffect(() => {
    fetchUserData(userId)
      .then(data => setUserData(data))
      .finally(() => setIsLoading(false));
  }, [userId]);
  if (isLoading) return <Spinner />;
  return (
    <div className={theme.card}>
      {userData && <UserInfo user={userData} />}
      {showDetails && userData && <UserDetails user={userData} />}
    </div>
  );
};
export default UserCard;
            

Densité verticale

Martin explique que "si l'ouverture sépare les concepts, alors la densité verticale implique une association étroite." Les lignes de code étroitement liées devraient apparaître densément ensemble. Dans un custom hook React, les lignes qui manipulent la même partie de l'état devraient être regroupées sans espacement, formant un "bloc conceptuel" densément organisé.

Distance verticale

Uncle Bob insiste : "Les concepts étroitement liés devraient être maintenus verticalement proches les uns des autres." Il définit plusieurs catégories de proximité verticale :

Ordonnancement vertical

Martin recommande un flux descendant : "les dépendances d'appel de fonction devraient pointer vers le bas." En d'autres termes, une fonction appelante devrait être au-dessus d'une fonction appelée. Cette organisation crée un flux naturel du haut niveau vers le bas niveau, permettant de comprendre le code en lisant de haut en bas, sans avoir à sauter entre différentes parties du fichier.

3. Formatage horizontal

Dans son analyse détaillée, Martin examine la distribution des longueurs de lignes dans sept projets différents et observe une régularité impressionnante. La majorité des lignes se situe entre 20 et 60 caractères, avec une diminution significative au-delà de 80 caractères. Bien que l'ancienne limite de 80 caractères des cartes Hollerith soit arbitraire, Martin suggère que les développeurs préfèrent manifestement les lignes courtes et recommande de ne pas dépasser 120 caractères.

Ouverture et densité horizontale

Martin explique comment utiliser l'espacement horizontal pour associer ce qui est fortement lié et dissocier ce qui l'est moins. Par exemple, entourez les opérateurs d'assignation d'espaces pour accentuer la séparation entre la partie gauche et droite, mais ne mettez pas d'espace entre les noms de fonctions et la parenthèse ouvrante pour montrer leur étroite relation. Ces principes sont particulièrement utiles en TypeScript, où la syntaxe de typage peut rapidement devenir dense et difficile à lire sans espacement approprié.

Espacement horizontal en TypeScript

// Difficile à lire
const calculateTotalPrice=(items:CartItem[]):number=>{
  return items.reduce((total,item)=>total+item.price*item.quantity,0);
};

// Bien formaté
const calculateTotalPrice = (items: CartItem[]): number => {
  return items.reduce((total, item) => total + item.price * item.quantity, 0);
};
            

Alignement horizontal

Martin partage son expérience personnelle avec l'alignement horizontal, qu'il utilisait autrefois pour accentuer certaines structures. Il montre des exemples où les noms de variables sont alignés dans des déclarations ou les valeurs dans des affectations. Cependant, il conclut que "ce type d'alignement n'est pas utile" car il tend à mettre l'accent sur les mauvaises choses et détourne l'attention de l'intention réelle du code. De plus, les outils de reformatage automatique éliminent généralement ce type d'alignement.

Éviter l'alignement artificiel en TypeScript

// Alignement artificiel - à éviter
interface UserData {
  id           : string;
  firstName    : string;
  lastName     : string;
  emailAddress : string;
  isActive     : boolean;
}

// Préférer des déclarations non alignées
interface UserData {
  id: string;
  firstName: string;
  lastName: string;
  emailAddress: string; 
  isActive: boolean;
}

// Le problème n'est pas l'alignement mais la longueur
// Si la liste est longue, considérez diviser l'interface
interface BasicUserInfo {
  id: string;
  firstName: string;
  lastName: string;
}

interface UserContactInfo {
  emailAddress: string;
  phoneNumber: string;
}
            

Indentation

Martin explique que "Un fichier source est une hiérarchie plutôt comme un plan". L'indentation rend cette hiérarchie visible en décalant les lignes proportionnellement à leur position dans la hiérarchie. Il présente deux versions du même code - l'une sans indentation et l'autre correctement indentée - démontrant comment l'indentation permet aux développeurs de repérer rapidement la structure du code, de sauter des blocs non pertinents et d'identifier de nouvelles méthodes ou variables.

Indentation en React/JSX

// Indentation claire qui reflète la hiérarchie du JSX
const ProductPage: React.FC = () => {
  const { productId } = useParams();
  const { data, isLoading, error } = useProductData(productId);
  
  // Gestion des états de chargement et d'erreur
  if (isLoading) {
    return <LoadingSpinner />;
  }
  
  if (error || !data) {
    return (
      <ErrorContainer>
        <ErrorMessage>
          Impossible de charger les informations du produit
        </ErrorMessage>
        <RetryButton onClick={refetch} />
      </ErrorContainer>
    );
  }
  
  // Rendu principal du produit
  return (
    <ProductContainer>
      <ProductHeader>
        <ProductTitle>{data.name}</ProductTitle>
        <ProductRating 
          score={data.rating} 
          reviewCount={data.reviewCount} 
        />
      </ProductHeader>
      
      <ProductGallery images={data.images} />
      
      <ProductDetails>
        {data.isOnSale && (
          <SaleBadge 
            discount={data.discountPercentage} 
            validUntil={data.saleEndDate} 
          />
        )}
        <ProductPrice 
          current={data.price} 
          original={data.originalPrice} 
        />
        <AddToCartButton productId={data.id} />
      </ProductDetails>
    </ProductContainer>
  );
};
            

Portées fictives

Martin met en garde contre les "dummy scopes" - des blocs vides ou avec juste un point-virgule. Il précise qu'il n'aime pas ces structures et essaie de les éviter. Quand il ne peut pas les éviter, il s'assure que le corps fictif est correctement indenté et entouré d'accolades. En React et TypeScript moderne, cela se traduit par l'évitement de blocs conditionnels vides ou de fonctions sans contenu significatif, préférant plutôt utiliser des opérateurs ternaires, des rendus conditionnels ou des composants à responsabilité unique.

4. Règles d'équipe

Martin intitule sa section "Team Rules" (Règles d'équipe) avec un jeu de mots intentionnel : chaque programmeur a ses propres règles de formatage préférées, mais s'il travaille en équipe, alors "the team rules" (c'est l'équipe qui décide). Il précise : "Une équipe de développeurs devrait s'accorder sur un style de formatage unique, et chaque membre de cette équipe devrait utiliser ce style." Il partage son expérience avec le projet FitNesse où l'équipe a passé seulement 10 minutes à définir un style de codage, l'a encodé dans le formateur de code de leur IDE, et s'y est tenu depuis.

Configuration recommandée pour React/TypeScript

Dans l'esprit de Martin, qui affirme qu'"un bon système logiciel est composé d'un ensemble de documents qui se lisent bien", voici une configuration moderne d'ESLint et Prettier qui implémente les principes de Clean Code pour les projets React et TypeScript actuels. Cette configuration peut servir de point de départ pour la discussion d'équipe recommandée par Uncle Bob.

Configuration ESLint pour React/TypeScript

// .eslintrc.js
module.exports = {
  parser: '@typescript-eslint/parser',
  extends: [
    'eslint:recommended',
    'plugin:react/recommended',
    'plugin:@typescript-eslint/recommended',
    'prettier',
    'plugin:react-hooks/recommended'
  ],
  plugins: ['react', '@typescript-eslint', 'prettier'],
  rules: {
    // Impose des règles de formatage cohérentes
    'prettier/prettier': 'error',
    
    // Limite la taille des fichiers
    'max-lines': ['warn', { max: 300, skipBlankLines: true, skipComments: true }],
    
    // Limite la complexité des fonctions
    'max-depth': ['warn', 3],
    'max-lines-per-function': ['warn', { max: 50, skipBlankLines: true, skipComments: true }],
    
    // Assure une distance verticale appropriée
    'padding-line-between-statements': [
      'error',
      { blankLine: 'always', prev: '*', next: 'return' },
      { blankLine: 'always', prev: ['const', 'let', 'var'], next: '*' },
      { blankLine: 'any', prev: ['const', 'let', 'var'], next: ['const', 'let', 'var'] },
      { blankLine: 'always', prev: 'directive', next: '*' },
      { blankLine: 'always', prev: 'block-like', next: '*' }
    ]
  },
  settings: {
    react: {
      version: 'detect'
    }
  }
};
            

Configuration Prettier

// .prettierrc
{
  "printWidth": 80,
  "tabWidth": 2,
  "useTabs": false,
  "semi": true,
  "singleQuote": true,
  "trailingComma": "es5",
  "bracketSpacing": true,
  "jsxBracketSameLine": false,
  "arrowParens": "avoid",
  "endOfLine": "lf"
}
            

Organisation du temps de mise en place

L'implémentation de bonnes pratiques de formatage nécessite un investissement de temps initial, mais qui sera rapidement rentabilisé.

À Retenir

  • Le formatage est communication : "Le formatage concerne la communication, et la communication est la première mission d'un développeur professionnel." Un code bien formaté reflète le professionnalisme de l'équipe.
  • Métaphore du journal : Comme un article de journal, structurez vos fichiers avec les concepts de haut niveau en haut, suivis progressivement par les détails. Limitez idéalement vos fichiers React/TypeScript à 200-300 lignes.
  • Gestion de l'espace vertical : Utilisez les lignes vides pour séparer les concepts, gardez proches les lignes conceptuellement liées, et maintenez les fonctions dépendantes à proximité verticale les unes des autres.
  • Simplicité horizontale : Évitez l'alignement artificiel, limitez vos lignes à 120 caractères maximum, et utilisez l'indentation pour représenter clairement la hiérarchie de la structure du code.
  • Règles d'équipe : "L'équipe devrait s'accorder sur un style de formatage unique et tous les membres devraient s'y conformer." Utilisez ESLint et Prettier pour appliquer automatiquement ces règles choisies en équipe.