La documentation ? Et pour quoi faire ?

Un billet pour un point méthodo, une fois n’est pas coutume, car il est important de savoir pourquoi on fait les choses.

Je m’explique tout de suite. On passe notre temps à optimiser notre code. On veut y mettre du composer, de l’autoload – de la joie, je vous le recommande au passage (sans ironie aucune ici) – on s’installe même des codes sniffer pour aller renifler les bourdes qu’on aurait pu laisser et pour amélorier la présentation du code.

Et tout ça pour parfois laisser du code non commenté qu’on sait pas ce que ça fait et qu’on va passer 10 minutes voire beaucoup plus à comprendre des mois plus tard.

Pas de documentation c’est pécher !

De plus en plus, dans la mesure du possible, autant que faire se peut, au maximum… enfin vous avez compris j’essaie de documenter ce que je fais. Ce n’est pas par pur plaisir, c’est une discipline !

Vous connaissez l’adage “si c’est pour faire une documentation naze reste chez toi”. Bon en fait je viens de l’inventer mais l’idée est simple : bien faire ou ne pas faire du tout. Et pourtant il faut faire et on a pas toujours le temps. Ce put*** de temps qui défile !

Pour autant la documentation n’est pas du bonus. C’est comme la sécurité c’est pas facultatif ou à ranger dans la case “on verra si j’ai le temps sinon bamos”.

Mais le coeur de la documentation c’est “le pourquoi” et “le comment”. On en a rien à carrer des params machin si on ne sait ce que fait la fonction. Quand on a la chance d’utiliser phpstorm, au quotidien la documentation est automatique. Je tape juste :

/**

Et je presse entrée, il me sort les params, la return value, etc… Je peux même aller paramétrer plus finement si je le souhaite dans les menu des réglages. MAIS, il ne me sort pas encore la raison d’être de la méthode et de la classe.

Vous pourrez installer tous les codes sniffer, mess detector et autres joyeuseries rien ne remplace encore l’humain en particulier pour expliquer le but du code.

Allez ensemble “gagnant gagnant” !

C’est toujours gagnant la documentation. Parfois, à devoir expliquer pourquoi on a fait comme ça, et bah on se dit qu’on aurait pu mieux faire et donc on va améliorer son code. On va se dire qu’on pourrait mieux organiser, factoriser, etc.

Après il ne faut pas basculer non plus dans l’optimisation à outrance et se mettre à rédiger un tutoriel pour chacune de ses méthodes et classes. C’est l’écueil à éviter. On n’est pas là pour écrire un roman de gare.

En revanche une explication concise de ce que fait la fonction c’est une seule phrase ! Pour peu que la fonction soit mal nommée en plus, du style vous l’avez appelé is_machin() et au dernier moment vous avez changé le code du coup la fonction ne retourne plus true/false, comme on pourrait s’y attendre avec un nom pareil, bah on y comprend plus rien si c’est pas documenté.

Revue de code

Un intérêt, parmi de nombreux autres, à bosser en équipe est de pouvoir confronter les avis, discuter des méthodes, demander conseil dans la mesure des disponibilités de chacun et ensemble on se tire vers le haut smile

C’est malgré tout assez délicat. Comme le travail est “purement intellectuel”, chaque critique renverra à la jugeotte, l’intelligence ce celui qui a rédigé le code. Y a toujours un contexte, les sensibilités de chacun et l’erreur est humaine et pierre qui roule… toussa toussa.

Prenons un cas général où une fonction est documentée tout bien comme il faut sauf qu’il fallait faire autrement ! C’est assez probable. Il suffit d’explorer le code de certains plugins, de se promener sur GitHub et on en trouvera du code à optimiser voire à corriger. Ouch ! La honte non ?

Et bien oui ou non mais c’est pas du tout important. Ce qui est bien est qu’en arrivant sur le code on est tout de suite renseigné sur l’objectif que poursuivait celui qui a codé. Plus il est facile de débusquer les erreurs dans un code mieux c’est. Je vous rappelle le principe :

un fork et ça repart !
Rien de pire que la dissimulation, “ni vu ni connu jt’embrouille”. L’autre fois on a vu un plugin WordPress.org qui dissimulait tout bonnement ses erreurs ! Voilà voilà pourquoi s’embêter à déboguer c’est vrai ça quelle idée… Y a des erreurs là ? des warnings ? bah tiens regarde y en a plus ! Boom magie !

La documentation qui ne sert à rien

Quelques exemples concrets :

/**
 * Class constructor
 */
public function __construct(){}

Ah oui ? J’avais pas compris merci smile

/**
 * Adds contextual help
 */
public function add_contextual_help() {}

C’est un peu redondant non ?

Faites-le pour vous ou pour les autres mais faites-le

Si vous ne le faites pas pour les autres faites le pour vous au moins.

Quand vous repasserez sur vos “chefs-d’oeuvre” quelques mois plus tard, outre les larmes que vous verserez devant un code qui a vieillit, vous serez content d’avoir un petit mémo qui vous rappellera pourquoi vous avez fait ça.

Et passez à Phpstorm ou installez-vous un plugin de doc (ex : dans Sublime) pour gagner un peu de temps mais n’oubliez pas les descriptions ! Je m’inclus dans le lot smile

Pour les classes aussi !

Bien souvent les méthodes et les fonctions seront documentées mais pas les classes. Or si vous pensez en MVC par exemple en général vous allez essayer de découper au maximum votre code dans des classes courtes, le but étant de favoriser la flexibilité et la réutilisabilité.

Donc avant de déclarer votre classe, une phrase sur le but de la classe, à quoi elle sert, dans quelle contexte elle sera utilisée, ne sera pas de trop.

2 liens utiles

Les liens suivants sont en Anglais :

Conclusion

On n’a evoqué ici qu’une partie de la documentation (la “plus essentielle” à mon sens). Il ne faut pas négliger les wiki sur GitHub, les readme sur WordPress.org, ne pas hésiter non plus à fournir des tutoriels liés à vos codes.

C’est beaucoup de travail mais parfois ça s’équilibre avec un peu moins de support par exemple. Rares sont les dév à vouloir forker un code imbittable, non documenté.

Enfin dans la mesure du possible donnez un contexte dans vos docs. Par exemple sur un projet pro, “We do this because…”, “Can be used for… but not for…”.