Questions de documentation

Pour quelques ressources d'ordre linguistique, vous pouvez consulter ../../Liens/Outils-linguistiques--Liens.html qui, sans être vaste ou exhaustif, propose quelques pistes et quelques outils pour mieux rédiger.

La documentation, prise au sens large, inclut plusieurs facteurs, dont le choix judicieux des noms, l'indentation, les commentaires, etc. Cela dit, voici quelques pistes et quelques liens portant sur la documentation du logiciel.

« You know what's worse than clever code? Clever undocumented code. Unfortunately the two are often correlated » – Caitie McCaffrey (source)

Le texte de Wooten ci-dessus contient un bel exemple d'un cas qui, à mon avis, ne devrait pas tant être de la documentation que du code. En effet, imaginez ceci (adapté du texte en question) :

//
// Calculer le temps requis pour traverser une distance
// étant donné une vitesse de déplacement
//
// @param distance : la distance à traverser
// @param vitesse : la vitesse de déplacement
//
// @return le temps requis pour traverser la distance
// « distance » à la vitesse « vitesse »
//
double calculerTempsDeplacement(double distance, double vitesse);

Le texte recommande d'indiquer les unités de mesure à même les commentaires (aussi adapté de ce texte) :

//
// Calculer le temps requis pour traverser une distance
// étant donné une vitesse de déplacement
//
// @param distance : la distance à traverser (en Km)
// @param vitesse : la vitesse de déplacement (et Km/h)
//
// @return le temps requis (en minutes) pour traverser la
// distance « distance » à la vitesse « vitesse »
//
double calculerTempsDeplacement(double distanceKm, double vitesseKph);

En pratique, je pense que nous devrions viser une écriture plus proche de celle-ci :

//
// Calculer le temps requis pour traverser une distance
// étant donné une vitesse de déplacement
//
// @param distance : la distance à traverser
// @param vitesse : la vitesse de déplacement
//
// @return le temps requis pour traverser la distance
// « distance » à la vitesse « vitesse »
//
Temps<Minute> temps_deplacement
   (Distance<Kilometre> distance, Vitesse<Kilometre, Heure> vitesse);

Imaginez cette interface même sans commentaires. Elle demeure, il me semble, très lisible :

Temps<Minute> temps_deplacement
   (Distance<Kilometre> distance, Vitesse<Kilometre, Heure> vitesse);

On peut même l'imaginer générique, donc plus flexible encore, sans perte de généralité ou de vitesse d'exécution :

template <class T, class D>
   Temps<T> temps_deplacement(Distance<D> distance, Vitesse<D, T> vitesse) {
      // code pour réaliser le calcul (peu importe)
   }
// ...
int main() {
   Temps<Minute> t = temps_deplacement(
      Distance<Kilometre>{5.5}, Vitesse<Kilometre,Heure>{60.0}
   );
   // ...
}

...du moins présumant des constructeurs de conversion corrects. Évidemment, en utilisant des littéraux maison, on peut en arriver à un programme comme celui-ci :

Distance<Kilometre> operator "" _km(long double);
Vitesse<Kilometre,Heure> operator "" _kmh(long double);
// ...
template <class T, class D>
   Temps<T> temps_deplacement(Distance<D> distance, Vitesse<D, T> vitesse) {
      // code pour réaliser le calcul (peu importe)
   }
// ...
int main() {
   auto t = temps_deplacement(5.5_km, 60.0_kmh);
   // ...
}

Si vous aimez l'écriture résultante, qui est selon moi plus robuste du fait que le compilateur peut alors assurer le respect du contrat sémantique de l'interface, ce contrat étant exprimé à même la syntaxe de ses paramètres, vous pouvez examiner l'article ../Divers--cplusplus/Implementer-changement-referentiel.html qui montre comment il est possible d'y arriver sans perte d'efficacité.

« Documentation is a love letter that you write to your future self » – Damian Conway (source)

« [Documentation] bugs are the most insidious kind » – Alisdair Meredith (source)

Ce que je fais, personnellement

Dans mon code, je documente peu (certains diraient trop peu, et sans doute avec raison), mais j'essaie de porter une attention particulière à quatre éléments, soit :

Chacun des liens ci-dessus donne plus de détails quant à ma pratique.

Formes auxiliaires de documentation

Nous avons aujourd'hui accès à des modalités nouvelles de documentation. En voici quelques-unes.

Blogues

Mode d'expression du XXIe siècle, le blogue (forme concise pour Web Log), que certains nomment « carnet », permet à un auteur d'exprimer ses idées et de les publier dans Internet sans intervention d'un tiers.

Foires aux questions (FAQ)

Il est fréquent que les gens posent, de manière récurrente, les mêmes questions, ou encore des questions tombant dans un même registre. Pour répondre à ces gens et à leurs besoins, il arrive souvent qu'une Foire aux questions (en anglais : Frequently Asked Questions), ou FAQ, soit mise en place. Pour vous aider, des outils et des trucs :

Les man pages

Sous Unix, depuis le tout début, la documentation en-ligne est disponible à travers ce qu'on y nomme des man pages, ou pages de manuel, à l'aide de la commande man.

Whitepapers

Il arrive, avec l'expérience, qu'on nous demande de rédiger un Whitepaper, soit un document semi technique donnant des pistes ou guidant les gens tentant de résoudre un problème ou une classe de problèmes. Typiquement, ces documents soutiendront une technologie et mettront, au passage, en valeur celle-ci et sa pertinence pour ce qui est de résoudre un problème comme ceux décrits dans le document. Si vous devez le faire, des pistes :

Autres

Une démarche unifiée de documentation des produits, par Microsoft : https://docs.microsoft.com/fr-fr/

Lisibilité du code

La lisibilité du code est une question éminemment sujbective. Tous la souhaitent, la majorité l'encourage, mais les définitions varient beaucoup selon les individus. Quelques opinions sur ce sujet :

Valid XHTML 1.0 Transitional

CSS Valide !