Un des principes que j’applique le plus lorsque je développe est celui de la règle du boy scout. La règle du boy scout est basée sur le fondement suivant : toujours laisser un endroit dans un état meilleur que celui où vous l’avez trouvé.
En programmation, cette règle signifie exactement la même chose lorsque vous effectuez un changement dans une classe. Le synonyme de ceci se résume (presque) ainsi.
Le contexte à l’origine de ce billet est lié au développement sur la plus grosse application web que moi et mon équipe faisons évoluer. Il s’agit d’une application qui a du vécu. Elle existe depuis 2007, pour vous dire.
Sans révéler de détails confidentiels sur cette application, je m’amuse à dire que, si cette application n’existait pas, mon équipe n’y serait pas non plus. Il s’agit de notre pain et de notre beurre. Près de la moitié de nos itérations à trois développeurs y sont dédiées. C’est quand même beaucoup d’heures de développement.
Or, puisqu’il est question d’une application âgée, dit code base qui a du vécu. Sur une ligne du temps, il s’agit d’une application qui a connu la transition de la fin de .NET 2.0 à .NET 4.5. À la lecture du code, il est intéressant de constater cette évolution dans les façons de coder et par le style de programmation de chacun des individus qui ont contribué au projet avec le temps.
Cependant, au-delà de la curiosité anthropologique, du code âgé signifie aussi qu’il y a du ménage à faire. En particulier aux endroits qui n’ont pas vu beaucoup d’évolution ces derniers temps. Une des pratiques que je tente d’endiguer dès que j’en ai l’occasion est ce que je nomme la surcommentarisation du code.
Je nomme cela aussi l’effet //this is bridge
Vous avez tous déjà vu un extrait de code qui ressemble à celui-ci.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| //Get the employee list | |
| var employees = EmployeeService.GetAllEmployees(); | |
| //Sort employee by name | |
| employees = employees.OrderBy(p => p.Name); | |
| //Send email to employee | |
| MailService.SendMail(employee.Email); | |
| //Get today's date | |
| vat today = DateTime.Now |
Je suis assez contre l’utilisation des commentaires dans du code. Je me dis qu’il s’agit de la pire documentation qui peut exister. Bien souvent, les commentaires ne font qu’ajouter du bruit inutile à du code qui aurait besoin d’être simplifié.
Parfois, un commentaire peut aider à expliquer un contexte derrière la mise en place d’une solution. À cela, je réponds que je préfère avoir un code plus explicite, mais qui décrit exactement qu’il fait. Par exemple, un commentaire peut être remplacé par une méthode avec un nom significatif qui englobe une ou deux lignes de code. C’est plus long, mais plus clair.
L’avantage est qu’une méthode avec une si petite portée est significativement plus facile à nommer. De plus, ces méthodes ont tendance à faire une seule chose et la comme il faut.
Même si je suis contre l’utilisation des commentaires, même s’il est rare, je concède qu’il peut toujours y avoir un bon contexte pour un commentaire. Tout est une question de modération. Cela est sans rappeler l’histoire du garçon qui criait au loup. À force d’inclure trop souvent des commentaires, on finit par perdre de vue l’essentiel avec le concept d’origine. C’est à dire mieux communiquer ses intentions et faire en sorte que les bogues se tiennent loin du troupeau.
French Coding 