Chroniques d'Améthyste

Comme l'année dernière je vais refaire une petite saga de l'été. Cete fois le thème sera l'authentification en ASP.

J'ai quelques idées sur ce dont je parlerai, mais les vôtres sont aussi les bienvenues.
Si vous avez des demandes n'hésitez donc pas, mais je ne fournis pas de garanties quand à une réponse.
Si vous avez lu un article interressant en anglais signalez le moi, j'essayerai d'en faire un compte rendu pour ceux qui ne lisent pas la langue de Shakespeare, de même n'hésitez pas à m'envoyer vos trucs ou vos bouts de code en n'oubliant pas votre nom afin que je puisse vous créditer. Si vous avez écrit un article je suis aussi preneur, je le mentionnerai dans la bibliographie.

Envoyez de préférence un message privé, merci.

Revenons au sujet de ce blog.

Récemment un collègue m'affirmait que rentrer /// puis compléter les tags qui sont automatiquement créés ça prend trop de temps sur le projet.

Je suis un farouche partisan de la documentation du code. Les histoires du genre "un code bien écrit n'a pas besoin de doc" je n'y crois pas.
Donc je documente.

Que répondre devant des affirmations qui à mon sens sont ridicules?

D'abord, si les quelques secondes consacrées à documenter une méthode suffisent à couler le projet, alors il est déjà mal en point et coulera de toute façon. Allez plutôt voir le chef de projet pour essayer de replanifier ou redéployer le périmètre du développement.

Et puis j'aime les idées simples.

Voici donc une idée très simple: documenter est un excellent moyen de savoir si le code est correct. Par expérience, j'ai souvent constaté que si l'on n'est pas capable de dire en 1 ou 2 phrases à quoi sert une méthode, une propriété ou une classe, alors elle est probablement mal conçue.
Un code mal conçu vous fera à coup sûr perdre plus de temps que de le documenter.

Si vous n'arrivez pas à expliquer clairement ce que vous avez fait, prenez le temps de tout relire, de réorganiser, réécrire ce qui doit l'être, redécouper autrement, restructurer...
Faites vous éventuellement aider, souvent un regard neuf fait des miracles. N'ayez pas de mauvaise fierté, même les gourous se sentent parfois honteux en relisant certaines de leurs productions.

Il arrive souvent que le commentaire approprié soit simplement le copier/coller de celui dans la classe de base ou se déduit aisément du nommage de la méthode. Pour vous éviter une laborieuse recopie je vous conseille vivement un outil: GhostDoc [1]. C'est un add-in pour Visual Studio qui d'un clic génèrera ce genre de documentation répétitive.

Cette réflexion s'inscrit dans quelque chose je crois plus vaste: c'est quoi un bon code?
La question est large et chacun à sa réponse j'imagine.

Par exemple on pourrai dire: c'est un code qui fait son boulot.
Oui mais ce n'est pas un critère, c'est l'essence même d'un code un tant soit peu utile.

Pour moi un bon code est un code maintenable avant tout autre chose.

Les deux principaux destinataires d'un code sont le compilateur et les gens qui feront la maintenance.
Je ne suis pas inquiet pour le compilateur qui a les moyens de se faire entendre, mais pensez aux autres.
Les autres connaîtront plus ou moins bien l'application, connaîtront plus ou moins bien le métier qui se trouve derrière, auront plus ou moins le temps, seront plus ou moins expérimentés...

Vous ne pourrez certes jamais supprimer la courbe d'apprentissage, mais essayez au moins de la rendre moins pentue.

Comprenez aussi que par définition un nouvel arrivant ne connait rien au projet et n'a pas comme vous baigné dans son contexte depuis des mois, ignore tout d'un certain jargon métier.

Il y a quelques années un client me donnait un document standard dans lequel je devais rédiger la doc technique de son application. Je n'oublierai jamais la recommendation qu'il y avait au chapitre "Description de l'application":

Ce texte doit être compréhensible par ma femme de ménage.

Alors, vous attendez quoi pour faire relire votre prose par votre concierge?

Pensez maintenance sacrebleu!!!!

Bibliographie

Ghostdoc, le genre d'outil qui bosse vraiment pour vous:

http://www.roland-weigelt.de/ghostdoc/