Avant de démarrer, je voudrais poser le problème. Lorsqu'on travaille sur un projet, il faut se dire que d'autres travaillent dessous ou avec aussi. Vous avez des collaborateurs, vous aurez des successeurs (quand vous serez chef et que vous direz à votre jeune recrue de documenter son code...), vous avez des utilisateurs. Si vous n'avez rien de tel, alors soit votre projet est mort, soit c'est un petit bout de programme qui ne sert qu'une fois et qu'on jette après utilisation.
Ces gens qui travaillent avec vous sur le projet doivent pouvoir comprendre ce qui les concernent dans le projet:
Un collaborateur aura besoin de suivre l'évolution du projet et de pouvoir comprendre le code pour y apporter ses modifications
Un utilisateur nouveau voudra avoir une description rapide du projet pour savoir s'il convient à ses besoins. Si oui, il lui faudra la documentation d'installation du logiciel, puis le manuel utilisateur.
Un utilisateur averti cherchera le manuel utilisateur puis très rapidement le manuel de référence.
Vous-mêmes, suivant vos capacités mémoires (les neurones, pas les barettes), aurez besoin de relire votre code et de comprendre ce que vous avez fait auparavant.
Il est donc important de documenter le projet, et commenter le code ne suffit pas, de loin. La suite va donc aborder différents points de la manière de documenter un projet.
Avant d'attaquer la suite, encore une précision. L'anglais étant la langue de l'informatique en plus d'être la langue dominante, tout projet doit être documenté en anglais au moins si le public visé dépasse notre petite France et autres zones francophones (bonjour au Quebec, à la Belgique et aux autres contrées francophones si nombreuses!). De plus si vous travaillez dans une entreprise dont des extensions (filiales, siege, services...) sont à l'étranger, il vaut mieux programmer en anglais aussi, même si vos collègues sont tous français. Si votre programme est utilisé dans un autre pays ou si un collaborateur étranger vient vous aider, cela évitera le franglais qui n'est pas aussi lisible qu'un code entièrement dans une langue. A l'école, cela est valable aussi, car si plus tard dans la vie active vous avez l'occasion de reprendre un TP que vous avez soigneusement conservé, il vaut mieux l'avoir en anglais tout de suite plutôt que d'avoir à traduire les variables et fonctions. C'est une habitude à prendre et une fois qu'elle est prise on n'y pense plus. Et les anglophobes ne programment pas parce que les langages de programmations utilisent des mots anglais! Bref, mes noms de fichiers, de variables et tout ce qui est suceptible d'être recopié tel quel dans un projet ont été mis en anglais. Ma prose utilise au contraire un maximum de mots français car le français reste une belle langue.
© 2001 Yves Mettier