Documenter son code, la clé du bonheur

Vous pourriez être tenté de penser comme moi lorsque je développais mes anciens sites : “pourquoi passer du temps à documenter des lignes de code assez simples au lieu de créer des tonnes de fonctions plus intéressantes et amusantes ? C’est absurde et c’est une énorme perte de temps pour un simple site web !”

Je n’aurais pas pu me tromper davantage : documenter son code apporte de nombreux avantages. Cela ne prend pas tant de temps et peut même être amusant si l’on utilise les bons outils.

Avant d’aller plus loin, rappelons que JavaScript et PHP, ou toute autre technologie côté serveur, ne sont pas les seuls langages à documenter : n’oubliez ni les feuilles de style CSS ni les bonnes vieilles pages HTML.

Mon conseil pour documenter le code : écrivez autant que vous pouvez, sans vous inquiéter du reste. Voici quelques craintes fréquentes :

• Cela prendra trop de temps : avez-vous pensé au temps nécessaire pour maintenir ce code des années après sa rédaction ?

• Le code deviendra illisible : c’est précisément pour cela qu’on a inventé le repliage du code et des commentaires. Les éditeurs suivants le prennent en charge :

  • Aptana  (en anglais)
  • Dreamweaver 
  • Notepad++  (en anglais)
  • TextMate  (en anglais)
  • et bien d’autres, comme UltraEdit  (page partiellement traduite), Zend Studio  (en anglais) et Visual Studio …

• Mon site sera trop lourd et les utilisateurs verront mes mauvais commentaires et mes fautes d’orthographe : c’est pour cela qu’on a inventé les outils de compression du code :

  • Pour les feuilles de style CSS  (en anglais)
  • Pour JavaScript : JSMin  (en anglais), ShrinkSafe (source d’origine indisponible), YUI Compressor  (en anglais), packer (source d’origine indisponible)…

Voyons donc s’il est si difficile d’ajouter de la documentation à un objet JavaScript :

/**
 * Generates a random string with the specified length
 * @param {Int} nLength The length of the random string
 * @param {Bool} bNoNumber When activated, no numbers will be used in the random string
 * @return {String} The random string generated
 */
sRandomString: function(nLength, bNoNumber)
{
  // ... code here ... //
}

Voici un exemple de commentaire HTML :

<div id="sampleDiv">
  <!-- This is an HTML comment -->
</div>

Et maintenant un commentaire CSS :

.body{
  /* This is a CSS comment */
  color: #FF0000;
}

Ce n’était pas si difficile, n’est-ce pas ? Alors ne soyez pas paresseux et commentez autant que possible. Les octets ne coûtent pas cher, les mots non plus ; le temps passé à comprendre un vieux morceau de code, si !