Documenter son code et son firmware

Que le code se lise sans qu'on ait dû l'écrire soi-même

Documenter son code et son firmware

Commenter utilement, structurer un README de module, et documenter l'architecture logicielle de votre projet.

Durée :
Difficulté :

Pré-requis :

Logiciels :

Machines/Outils :

Documentation réalisée à 55% 55
Créée par :  Adrien Bracq

Deux niveaux de documentation de code

  • Le niveau fichier/fonction : des commentaires directement dans le code, pour qui le lit ligne par ligne.
  • Le niveau projet : un README ou une page qui explique l’architecture générale, avant même d’ouvrir un fichier.

Les deux sont nécessaires — l’un sans l’autre laisse toujours un trou.

Commenter utilement, pas commenter beaucoup

// incrémente i
i++;

// boucle
for (int i = 0; i < 10; i++) {
  // fait le calcul
  x = x + i;
}

// Moyenne glissante sur les 10 dernières mesures du capteur,
// pour lisser le bruit de lecture (voir tests, doc/etudes.md)
for (int i = 0; i < 10; i++) {
  somme = somme + mesures[i];
}
  La règle simple

Un commentaire ne doit jamais répéter ce que le code dit déjà — il doit dire ce que le code ne peut pas dire : pourquoi ce choix, ce que fait cette valeur magique, ce qu’il ne faut surtout pas changer et pourquoi.

Documenter l’architecture

Une page (dans docs/, ou un README.md dans le dossier du code) qui répond à : comment le code est organisé en fichiers/modules, quelles librairies utilisées et pourquoi (lien avec Tracer ses choix techniques), et comment flasher/lancer le tout.

Copier le gabarit d'architecture (Markdown) 
## Architecture du firmware

- `main.ino` : boucle principale, lecture capteurs et pilotage moteur
- `capteur_couleur.h/.cpp` : lecture et calibration du capteur TCS3200
- `moteur.h/.cpp` : pilotage du moteur pas à pas via le driver A4988

## Librairies utilisées

- `AccelStepper` — gestion du moteur pas à pas, choisie pour son support natif de l'accélération

## Flasher le firmware

1. Ouvrir `main.ino` dans l'IDE Arduino
2. Sélectionner la carte : ...
3. Téléverser

Exercice

Relisez votre code : supprimez les commentaires qui répètent l’évident, ajoutez-en sur les parties qui vous ont demandé réflexion. Rédigez ensuite une courte page d’architecture avec le gabarit ci-dessus.

Contents