Commenting comment: Comment commenter quelque chose qui est utilisé ailleurs dans l'application?

Question

Mon application IVR contient un grand nombre de variables globales, en tant qu'effet secondaire d'une infrastructure fournisseur incontournable. En tant que tel, il y a beaucoup de cas où une variable est donnée une valeur sur un JSP, et n'est pas touchée à nouveau jusqu'à ce qu'un appelant ait passé plusieurs boîtes de dialogue profondément dans l'application.

Quand je dois ajouter ou modifier une telle variable, je laisse un commentaire de préambule qui décrit la modification, sans entrer dans les détails sur l'ensemble morceau de fonctionnalité:

<%--IVRAvenger 20100927 Issue#:12345: Keep track of what the caller entered. Used for multiple ID/ID change logic, further on. --%> 
<assign name="gblIDInput" expr="memberID"/> 

Est-ce trompeur? Serait-il préférable d'ajouter simplement ces petites déclarations, et laisser d'autres développeurs analyser le code du module où ces variables fonctionnent leur magie (douteuse)?

Merci,
IVR Avenger

Answer 1

Avec un tel problème, je recommanderais un document de dictionnaire externe qui répertorie les variables globales, le but et le travail typique des flux qui leur sont associés.

Vous pouvez également répertorier les principaux modules utilisant les variables. Bien que ces données soient périmées, elles constitueront un point de départ pour les personnes ayant des difficultés à gérer votre demande.

Si vous mettez en œuvre un tel document, je recommanderais également tous les modèles ou philosophies globaux qui sont incorporés par le code. Y compris les mauvais choix connus et pourquoi ils étaient mauvais choix ne feraient pas de mal. Puisque la plupart des développeurs ne liront pas (et bien sûr maintiendront) un tel document, vous écrivez soit pour le nouvel employé qui a reçu de la documentation comme tâche, soit pour un futur responsable qui sera finalement assez frustré pour lire la documentation.