Dix-neuf pourcents de commentaires…

Si l’on regarde l’ensemble des projets open-source, on trouve en moyenne près d’une ligne sur cinq de commentaires, selon un papier de Dirk Riehle (voir également sur son blog).

On y lit que les projets étudiés restent tous très proches de ce taux. Un peu plus surprenant, on découvre que cette densité de très exactement 18,7% de commentaires est la même quelles que soient la taille du projet et la taille de l’équipe Shock . L’article propose l’explication que c’est dû à une grande auto-discipline de développeurs, très probablement motivée par l’exposition publique du code source à conjointement au nom de son contributeur.

Autre information de cette étude : ce qui influe sur le taux de commentaires est l’âge du projet. Quand un projet avance en maturité son taux de commentaires baisse (enfin d’un chouïa, à 18%). Je suppose que lorsque l’on maintient un code depuis plusieurs années, certaines choses deviennent tellement comprises, partagées et habituelles qu’elles en deviennent implicites, du coup on aurait l’impression d’écrire des évidences dans les commentaires en détaillant trop…

Ces statistiques soulèvent quelques petites questions…    Par exemple, peut-on considérer ce taux comme idéal ? En effet, c’est le taux auquel des développeurs volontaires et auto-organisés aboutissent à moyen terme, quel que soit le projet. Moins de commentaires c’est pas assez, mais plus de commentaires c’est inutile, voire c’est introduire du bruit. Si l’on admet ce taux comme “idéal”, le taux de commentaires de mes développements s’éloigne-t-il significativement de ce chiffre ? Quelle conclusion en tirer ? Ainsi, vous est-il déjà arrivé comme à moi, de vous dire qu’avant de diffuser tel ou tel de vos composants en open-source, il faudrait faire un petit effort de packaging et de documentation ? Blush

Question, en guise de conclusion : si vous imposez de préciser dans les commentaires le ou les auteur(s) de toute classe et méthode par exemple (c’est-à-dire en Java : @author partout), est-ce que vous obtiendrez un code globalement mieux commenté et/ou plus lisible ? Twisted