La documentation

La documentation du code et programme lettré

La documentation du code est une pratique très importante dans le développement de logiciels. Elle permet non seulement de rendre le code compréhensible pour d’autres développeurs, mais aussi de faciliter la maintenance et l’extension du logiciel. Un programme lettré (literate programming) est une méthodologie qui combine le code et la documentation dans un même document, rendant le processus de développement plus fluide et compréhensible.

Pourquoi documenter le code ?

Faciliter la compréhension : La documentation permet aux autres développeurs (et à vous-même dans le futur) de comprendre rapidement le fonctionnement du code.
Améliorer la maintenabilité : Un code bien documenté est plus facile à maintenir et à modifier.
Assurer la qualité : La documentation aide à vérifier que le code respecte les spécifications et les bonnes pratiques.

Types de documentation

Commentaires : Ce sont des commentaires insérés directement dans le code pour expliquer des lignes ou des blocs spécifiques.
```
# Calculer la somme de deux nombres
def addition(a, b):
    return a + b
```
Docstrings : Utilisées pour documenter les modules, classes, fonctions et méthodes. Elles fournissent une description plus détaillée et structurée. C’est la méthode officielle pour documenter son code en python. Les docstrings sont utilisées par certains outils pour générer une documentation automatique sous forme de page html par exemple (pydoc)
```
def addition(a, b):
    """
    Calcule la somme de deux nombres.

    Paramètres:
    a (int, float): Le premier nombre.
    b (int, float): Le deuxième nombre.

    Retourne:
    int, float: La somme des deux nombres.
    """
    return a + b
```
Documentation externe : Documentation séparée du code, généralement dans des fichiers Markdown ou reStructuredText, souvent utilisée pour les projets plus grands. Il peut s’agir également de document word, ou une plateforme de documentation en ligne.

Quelques outils pour la documentation externe en Python
- Sphinx : Un générateur de documentation qui crée des documents lisibles à partir de docstrings.
- pydoc : Génère une documentation HTML simple directement à partir des docstrings du code.
- MkDocs : Un générateur de documentation statique qui utilise Markdown.

La programmation lettrée (Literate Programming)

La programmation lettrée est une approche qui combine la documentation et le code dans un seul document. L’idée est de créer un récit compréhensible pour les humains, dans lequel le code est intégré de manière fluide.

Cette approche permet de lire et comprendre le code comme une histoire, ce qui peut être très utile pour l’apprentissage et la collaboration.

De nos jours, c’est la forme d’écriture la plus répandue dans la communauté scientifique aujourd’hui. Le format le plus utilisé est le notebook jupyter. Ces documents regroupent du texte en langage naturel au format markdown (md) et du code python. On peut y insérer des images pour illustrer le propos dans le texte, ou encore ces images peuvent être le résultat d’exécution du code.

Dans l’exemple ci-dessus, on voit un mélange de texte contenant des équations mathématiques, du code python et les résultats relatifs à l’exécution du code.