Le Touilleur Express

  • Accueil
  • A propos de l’auteur
  • A propos du Touilleur Express

Et elle est où la doc ?

6 février, 2016
@casanowe

@casanowe

Jeudi après-midi vous êtes en train de coder frénétiquement, le casque isophonique sur les oreilles, en mode « faut pas me déranger sauf si c’est la fin du monde« .

Christophe et Pierre débarquent devant vous dans l’open-space. Malgré votre effort pour leur montrer que vous êtes concentré, ils tiennent absolument à vous parler et se dirigent vers votre bureau. Vous tentez de rester super concentré, en vous disant que si vous ne bougez pas, ils ne vous verront pas. Mais bon, comme vous êtes une personne sympa, à l’écoute, vous retirez votre casque, et là, la question de Pierre tombe :

« Nicolas, sur ton module Vanessatra, elle est où ta doc ? »

Il se trouve que vous avez créé il y a plusieurs mois l’un des composants de chargement de fichiers du système. A l’époque c’était quelques lignes, qui sont devenues un vrai projet, avec des vrais clients qui s’en servent. Vous avez écrit un README en markdown, attaché au projet, et pour vous c’est ça la doc.

Pierre est le tuteur de Christophe, qui a rejoint l’équipe, et qui doit ajouter une fonctionnalité sur ce produit.

A priori votre documentation est incomplète et en plus, elle n’est pas à jour. Entre temps vous êtes passé sur PostgreSQL, et une partie du README est obsolète.

Bref, psychodrame, que faut-il faire et comment gérer finalement la documentation d’un projet ?

Je vous propose quelques pistes et idées.

Comment documentez-vous vos projets ?

Javadoc, Word, schémas, diagrammes, Markdown, AsciiDoc… nous avons tous écrit de la documentation sur nos projets.

J’ai écrit des lignes et des lignes de documentation, de spécifications et dessiné un sacré nombre de schémas. Lorsqu’il s’agit de faire des schémas ou des diagrammes, Microsoft Visio est pratique. J’utilise aussi LucidChart un équivalent en ligne. Sur Mac je n’ai pas trouvé pour l’instant de logiciel pratique.

J’utilise Markdown ou AsciiDoc lorsque je dois expliquer une procédure d’installation ou les pré-requis, et que je souhaite que la documentation soit stockée avec le code source, et qu’elle soit versionnée en même temps que les évolutions de celui-ci.

Il existe des outils plus évolués comme Structurizr par exemple, qui permet d’envoyer une description d’un projet sous forme de code Java, et qui génère en retour un diagramme simplifié. C’est un peu l’équivalent du tableau blanc où vous avez l’habitude de dessiner, sauf qu’ici l’outil est intégrable à un build continu par exemple. Simon Brown, son créateur, sera à Devoxx France 2016, il est invité.

Il est toujours plus intéressant d’expliquer les Pourquoi d’un projet, plutôt que de se focaliser que sur les Comment ou les Quoi. En débutant sa documentation par un paragraphe de justification ou d’historique, vous donnerez un contexte à votre code. Ensuite seulement, vient la description de l’architecture et la documentation plus technique sur le projet.

A titre personnel, je ne rédige plus vraiment de spécifications techniques ou fonctionnelles, et je vais vous expliquer pourtant comment nous arrivons à travailler en équipe, sans problèmes de communications.

Pour quel lecteur ? Qui vous lira (ou pas) ? 

Pour qui suis-je en train d’écrire ce document ? Que doit-il connaître avant de commencer à lire ma documentation ? Quels problèmes doit-elle résoudre ?

Nouveau développeur, client, contributeur sur votre projet open-source, responsable technique, chef de projet, utilisateur final…

Les limitations de la documentation classique

Ecrire de la documentation, puis s’assurer qu’elle est à jour, peut représenter une charge de travail trop couteuse pour certains projets. Si finalement votre module ne sera utilisé que par 2 personnes internes, quel est l’intérêt économique d’écrire un roman de 50 pages sur l’installation ?

L’effort de documenter un projet ou une procédure d’installation doit être limité dans le temps, selon la cible visée. Il est évident qu’un guide du contributeur pour Docker doit être très complet et détaillé, vu le nombre de personnes qui souhaitent contribuer à ce projet. A contrario, votre petite librairie sympa en Go, à usage interne, n’a pas forcément besoin d’une documentation parfaite.

Oui mais alors comment éviter d’être dérangé (blague) et comment documenter ?

Le code c’est de la doc

Evidence toujours bonne à redire : le code d’un logiciel est fait d’abord pour être lu par un humain, ensuite par une machine. Et une machine, je pense à la VM Java par exemple, est à même d’optimiser largement l’exécution du code, ce qui rend bien souvent inutile l’optimisation à tout prix d’un bout de code. Pensez d’abord que vous même, et peut-être un autre développeur, relira ce code dans 10 jours ou dans 3 mois.

En êtes-vous fier ? Pouvez-vous expliquer à votre fils de 10 ans ce que fait cette fonction ? Avez-vous effacé la balise @author tellement vous regrettez ce qui vient d’être écrit ? Avez-vous essayé de relire le code après une soirée trop arrosée pour voir si vous le comprenez toujours ?

Bref chacun sa technique, mais du code propre est la base d’une documentation vivante et à jour. Cela s’effectue avec des techniques de modélisations (DDD mais pas que).

A contrario, trop de javadoc/scaladoc pour moi, c’est aussi un pattern que le code est trop compliqué. Ne trollez pas sur Scala les chéris, les plus belles oeuvres que j’ai vu sont dans le monde Java. Mais bon, lorsque tu as 50 lignes de Javadoc pour 10 lignes de code, hem, ça poutre pas des masses.

Les tests aussi

Tester c’est documenter. Cela permet à un nouvel arrivant de comprendre ce que vous avez voulu faire, quels sont les cas limites de votre code, et bon sang, oui vous avez vraiment écrit ce code après le pot de départ d’un collègue. Mais passons.

Les tests unitaires, d’intégration, de désintégration, de comportements, en production, bref les « Tests » en général représentent un excellent moyen d’expliquer comment fonctionne votre projet.

Et enfin l’humain, la meilleure documentation

Enfin pour terminer, avec mes années d’expérience, j’ai trouvé que l’humain est plutôt pas mal aussi pour documenter et venir expliquer comment fonctionne un logiciel. Ce que l’on peut dire c’est que rien ne remplace une tasse de café échangée, autour d’un écran, où d’un air désolé vous expliquerez à Christophe pourquoi vous avez écrit ce code à 22h30 après le pot de départ de Bob, et que oui, c’est de la merde.

L’humain évidemment peut démissionner ou partir élever des e-chèvres sur Farmville, donc un peu de documentations « old-school » c’est pas mal aussi.

Mais c’est le meilleur outil jamais inventé, pour expliquer le fonctionnement d’un logiciel, pour aider Christophe, le petit nouveau, et surtout pour créer un lien social entre vous.

 

Dans le code écrit récemment d’un projet, sur une partie un peu hard-core j’ai laissé ce commentaire pour que le prochain relecteur vienne me voir. Ce sera l’occasion de prendre un café, que je me force à améliorer ce code et à le rendre plus lisible.

// TODO venir voir Nicolas le jour où quelqu'un lit ce code
// Ici un mot d'excuse pret à découper

// ---------------------------------------------------------
// |  J'ai écrit du code à l'arrache et je suis désolé      |
// ---------------------------------------------------------


Et donc toute ressemblance avec la réalité, tout ça, bla bla bla

Documentez et codez

Pour aller plus loin, je vous recommande le livre « Living Documentation » par Cyrille Martraire.

Articles similaires:

Default ThumbnailStartup : la photo non contractuelle Default ThumbnailLe gars qui connaît Scala et celui qui débute Default ThumbnailLancement de Google Buzz, le tueur de Twitter ?
  • Fedou 7 février 2016 at 16 h 56 min

    Bonjour,
    Pour avoir un code parlant, qui porte sa propre documentation tu parles de techniques de modélisation comme DDD.
    J’aurais mis en avant le Clean code pour avoir un code qui utilise le même vocabulaire que les analystes.
    Et merci pour l’article, il est simple et clair.
    Cordialement, Nicolas

  • Kabhal 19 février 2016 at 17 h 38 min

    Pour les schémas sur Mac, je conseille vivement Omnigraffle 🙂

Chercher

Derniers articles

  • Vis ma vie de Staff/Principal Engineer
  • Devenir Staff Engineer : comment et pourquoi ?
  • WeAreDevelopers 2022, conférence à Berlin – jour 1
  • Le chiffrement de bout en bout et la signature d’enveloppe
  • L’entretien de recrutement « System Design »

Commentaires récents

  • Nicolas Martignole dans Vis ma vie de Staff/Principal Engineer
  • Matt dans Vis ma vie de Staff/Principal Engineer
  • Sébastien dans Vis ma vie de Staff/Principal Engineer
  • BLA dans Devenir Staff Engineer : comment et pourquoi ?
  • Sébastien dans Devenir Staff Engineer : comment et pourquoi ?

Les plus lus

  • Les revenus d’un informaticien indépendant en EURL - 88 993 affichage(s)
  • Optional en Java 8 - 68 648 affichage(s)
  • Changer la batterie d’un MacBook Pro de 2011 - 64 877 affichage(s)
  • Retour sur la soirée du lundi 12 juillet chez Doctolib - 61 746 affichage(s)
  • Quelle est la différence entre volatile et synchronized ? - 60 712 affichage(s)
  • Un modèle de Product Backlog et de Sprint Backlog avec Excel - 56 040 affichage(s)
  • Redis, découverte d’un moteur clé-valeur simple et puissant - 50 225 affichage(s)
  • Comment simuler le navigateur de l'iphone avec Firefox ou Safari ? - 44 968 affichage(s)
  • serialVersionUID mythes et légendes - 41 173 affichage(s)
  • Développeur après 31 ans ? Ridé et chauve tu seras - 38 850 affichage(s)

Mots clés

agile ajax Apple architecture barcamp BarCampJavaParis ddd devoxx esb exo flex geek google grails groovy humeur humour independant iphone Java javascript jazoon jboss jboss seam jsf jug Linux mac mule paris jug parisjug pjug play playframework portlet recrutement ria Scala scrum spring Startup usi usi2010 web xebia

Derniers articles

  • Vis ma vie de Staff/Principal Engineer

    Suite de l’article précédent sur le Staff Engineer. Aujourd’hui, voyons un peu

    20 juillet, 2022
  • Inari

    Devenir Staff Engineer : comment et pourquoi ?

    Après une dizaine d’années en tant que développeur, vous serez un jour

    17 juillet, 2022
  • WeAreDevelopers 2022, conférence à Berlin – jour 1

    Il est 8h40, 19 degrés, vous êtes à Berlin. La queue dehors

    24 juin, 2022

Tweets @nmartignole

  • RT  @katecrawford : Umm, anyone a little concerned that Bard is saying its training dataset includes... Gmail? I'm assuming that's flat out…

    2 days ago
  • Je découvre qu’ils apprennent le SQL en Terminal, très intéressant https://t.co/MrfcHve9wo

    3 days ago
  • RT  @AmelieBenoit33 : Je m’essaye à de nouveaux formats ! Un premier sketch qui me trottait en tête depuis le sketchnote précédent; la techn…

    4 days ago

Mots clés

Apple (32) Architecture (13) Big Data (5) Conference (8) Devoxx (55) Dev Web (37) Doctolib (2) geekevent (1) groovy (2) Innoteria (11) Java (517) Linux (10) Non classé (14) Perso (266) Recrutement (3) Scala (30) scrum (43) Société (3) Startup (20) Web 2.0 (67)

Le Touilleur Express

Blog par Nicolas Martignole

Contactez-moi : nicolas@touilleur-express.fr

Suivez-moi sur Twitter : @nmartignole

Copyright© 2008 - 2020 Nicolas Martignole | Tous droits réservés
  • A propos de l’auteur
  • A propos du Touilleur Express
  • Log In
  • My Account
  • My Profile
  • Reset Password

Le Touilleur Express