Documentation en Swift : comment écrire un code qui parle de lui-même

Pourquoi la documentation est un super-pouvoir pour le développeur

Imaginez : vous ouvrez un projet Swift écrit par quelqu'un d'autre six mois après sa création. Le code fonctionne, mais comprendre pourquoi l'auteur a fait ce choix plutôt qu'un autre est impossible. Pas de commentaires, des noms de variables comme a1, temp2. Cela vous dit quelque chose ?

Une bonne documentation n'est pas seulement une politesse envers votre futur vous. C'est un outil qui permet d'économiser des heures de débogage, d'accélérer l'intégration des nouveaux développeurs et de transformer le chaos en un système structuré. Dans cet article, nous allons explorer les meilleures pratiques de documentation du code Swift, des commentaires de base au DocC avancé.

Les bases : des commentaires simples aux descriptions pertinentes

//, /// et /* */ — quand utiliser quoi

Swift propose trois types de commentaires, chacun ayant un objectif spécifique :

• Les commentaires sur une seule ligne // — pour les notes rapides, les TODO ou la désactivation temporaire de code. À utiliser avec modération : si un commentaire explique l'évidence, il est superflu.
• Les commentaires multi-lignes /* */ — pour des blocs d'explications ou la désactivation de sections entières de code lors du débogage.
• Les commentaires de documentation /// — c'est votre outil principal. Xcode les détecte automatiquement et les affiche dans l'aide rapide (Quick Help).

/// Calcule l'aire d'un cercle à partir de son rayon./// - Parameter radius: Le rayon du cercle en mètres./// - Returns: L'aire en mètres carrés./// - Throws: `InvalidInputError.negativeRadius` si radius < 0.func areaOfCircle(radius: Double) throws -> Double {    guard radius >= 0 else {        throw InvalidInputError.negativeRadius    }    return Double.pi * radius * radius}

Mauvais commentaire vs bon commentaire

Comparez les deux approches :

// MAUVAIS : Commentaire évident// Incrémente le compteur de 1counter += 1

// BON : Explique le "pourquoi"// Nous utilisons un incrément car il s'agit d'une section critique// pour les performances, et l'opération ++ est obsolète en Swiftcounter += 1

Règle d'or : un commentaire doit répondre à la question « pourquoi », pas « quoi » fait le code. Le code lui-même doit être lisible pour que le « quoi » soit compris sans mots.

DocC — la documentation de nouvelle génération

Qu'est-ce que DocC et pourquoi est-ce un incontournable

Avec l'arrivée de Xcode 13, Apple a présenté DocC (Documentation Compiler) — un outil qui transforme vos commentaires /// en une documentation interactive et élégante, directement dans Xcode et sur le web. Fini les fichiers PDF et les pages wiki qui deviennent obsolètes en une semaine.

Comment utiliser DocC dans un projet

1. Configuration : Dans Xcode, sélectionnez Product → Build Documentation. DocC compile automatiquement tous les symboles documentés.
2. Liens dans la documentation : Utilisez `` pour créer des liens vers d'autres types :

/// Utilisez ``NetworkManager`` pour envoyer des requêtes./// Pour plus de détails, consultez l'article <doc:NetworkGuide>.

3. Fonctionnalités Markdown : DocC prend en charge les titres, listes, tableaux, images et même les diagrammes Mermaid :

/// # Algorithme de fonctionnement/// 1. Vérification du cache/// 2. Si absent — requête au serveur/// 3. Sauvegarde du résultat

Créer une documentation pour un module entier

Ajoutez un fichier Documentation.docc à la racine du projet. À l'intérieur, une structure en Markdown :

// MyFramework.docc/MyFramework.md# ``MyFramework``

Bibliothèque asynchrone pour la gestion du réseau.

## Topics

### Composants principaux- ``NetworkManager``- ``RequestBuilder``

### Extensions- <doc:CustomizingRequests>

Techniques avancées : écrire une documentation qui est lue

Structurer par rôles

Tout le code ne nécessite pas le même niveau de détail. Divisez la docume