Blog Arolla

Ecrire du code, un travail rédactionnel comme un autre

Le développement logiciel, qui pourtant n’en est pas à sa première décennie d’existence, n’en demeure pas moins une discipline jeune, et on sent que c’est un monde qui se cherche; Beaucoup de débats ouverts, et bon nombre de métaphores pour s’assimiler à des métiers existants de plus longue date: comparaison avec la construction d’un bâtiment, industrialisation du cycle de vie du logiciel, assimilation à la catégorie des artisans (mouvement Software Craftsmanship), etc.
En ce qui me concerne, je considère de plus en plus qu’un des aspects non négligeable de notre métier est la rédaction. Bon nombre de personnes rédigent des documents: que ce soit l’écriture d’un livre, ou plus proche de nous les personnes en charge d’écrire la documentation, les spécifications, les contrats, etc.
De même nous “écrivons” toute la journée, certes dans un style très technique, en langage principalement destiné à la machine, mais certains traits d’exigence du travail rédactionnel s’y retrouvent:

Être intelligible

En effet, votre code va être lu par d’autres développeurs, qui voudront corriger, améliorer ou faire évoluer votre code, et pour cela ils devront comprendre ce que vous avez voulu faire.
De la même façon qu’il sera laborieux et fatiguant de lire un livre ou une spécification écrit en langage ‘petites annonces’ (jh ch. apt prox. com. av balc), il sera préférable d’avoir du code compréhensible.

Il faudra donc éviter ce style

public long calcProf(double pa,double t,double pv,double t2) {
return (pv/(1+t))-(pa/(1+t2));
}

au profit de celui-çi:

public long calculDuProfit(PrixTTC prixAchat,TVA tvaAchat,PrixTTC prixVente,TVA tvaVente) {
PrixHT prixAchatHT = tvaAchat.reduceFrom(prixAchat);
PrixHT prixVenteHT = tvaVente.reduceFrom(prixVente);
return prixVenteHT.moins(prixAchatHT);
}

Cohérence globale

Imaginez maintenant que vous écrivez un livre à plusieurs: on vous fait le résumé de l’histoire, chacun prend un chapitre et c’est parti !
Si vous ne communiquez pas, vous risquez d’avoir plusieurs fois le récit de l’attaque du dragon écrit avec des nuances différentes et aucun passage n’expliquant comment les héros sont arrivés là….et si vous ne vous êtes pas mis d’accord sur un style commun le rendu sera perturbant à lire.
Pour le développement c’est pareil ! Il faut une cohérence globale en terme d’architecture de code et de style, afin qu’il soit possible de trouver facilement ce que l’on cherche une fois que l’on connaît un minimum l’application. En résumé: parlez vous. Une équipe qui ne communique pas court à sa perte.
(ce parallèle là est un peu capillotracté…mais je reste persuadé que le fond fait sens)

Relecture

Je ne pense pas qu’un seul travail de rédaction soit envoyé pour livraison sans relecture (à part le développement logiciel … qui est rarement relu).
Aucune maison d’édition n’enverrait un livre à l’imprimerie sans relecture juste pour ne pas froisser l’ego de l’auteur. La plus grande barrière a la relecture du code reste, je pense, un problème de fierté, la relecture s’apparentant à du flicage. Rappelons qu’il n’est pas obligatoire que la relecture se fasse par un supérieur hiérarchique, cela peut se faire entre pairs et dans un bon état d’esprit.

La relecture de code c’est:
– un pas de plus vers la propriété collective du code
– un bon moyen de partager la connaissance
– avoir un avis extérieur sur son code

Pensez-y

Un code difficile à lire provoque une perte de temps, une fatigue intellectuelle et devient source d’erreur.
La compréhension d’un code vient aussi du suivi collectif qui en a été fait avant, via le partage de connaissances et le dialogue au sein de l’équipe.
Donc pensez-y lorsque vous développez, essayez de penser à la prochaine personne qui va venir lire votre code, et essayez donc de lui donner un coup de pouce.
Si vous ne le faite pas pour lui faites-le pour vous, car il y a de grandes chances que le prochain lecteur de ce code soit le vous du futur 🙂

4 comments for “Ecrire du code, un travail rédactionnel comme un autre

  1. 6 décembre 2014 at 12 h 39 min

    Bonjour Maury Fabien;
    Je suis tout à fait d’accord, un code doit être le plus compréhensible possible, l’effort doit être fourni par le programmeur.
    Que pensez-vous des documents de rédaction bien rédigés qui peuvent être fournis avec un code ? Pensez-vous que c’est nécessaire d’en faire ou qu’un code bien écrit suffit largement ?

  2. Maury Fabien
    9 décembre 2014 at 15 h 04 min

    Bonjour,
    Vous parlez par exemple des spécifications que l’on retrouve sous formes de fichier words ou de pages confluences dans nos projets ?
    Quoi qu’il en soit, en effet le “code” en soit ne peut suffire car tout le monde n’est pas développeur sur un projet.
    Et surtout mon point de vue de développeur est qu’un nouvel arrivant ne doit pas avoir à effectuer une double lecture (code + doc métier) pour comprendre le code applicatif.

    Mais le problème de la documentation texte est que si on ne la met pas à jours, elle devient obsolète (elle n’ait d’ailleurs que très rarement versionnée par version applicative, comme le sont nos branches sur nos répo de sources) …. et je suis persuadé que plus cette documentation est longue et verbeuse, plus elle a des chances de ne pas être mise à jours.

    C’est pour cela que les thèmes tournant autour de la “living documentation” et des “specifications by example” sont intéressants, car la tendance à vouloir rendre exécutable vos spécifications (Behavior Driven Development) les forcent à rester à jours.
    J’avoue ne pas avoir de solution “clé en main” sur le sujet, j’ai par contre l’impression qu’il bouge dans le bon sens.

Laisser un commentaire

Votre adresse de messagerie ne sera pas publiée. Les champs obligatoires sont indiqués avec *