Documenter le code et l’architecture

13 mai 2019

Trop souvent, la documentation est laissée de côté car les développeurs n’ont pas le temps de la tenir à jour. Cependant une bonne documentation est cruciale pour la réussite de votre projet : elle permet de comprendre globalement le fonctionnement du code, de savoir quelles parties du code sont impactées par une modification, etc.

  • Documentez l’architecture, pas uniquement le code

Ecrire une documentation n’est pas la même chose que commenter du code. La documentation doit notamment porter sur l’architecture de votre projet et sur les relations entre ses différentes parties.

Vous devez ainsi garder une vision d’ensemble lorsque vous écrivez votre documentation : elle doit aider les développeurs à comprendre de manière globale le fonctionnement de tous vos composants. En conséquence, privilégiez les schémas et des explications claires lorsque vous documentez votre projet.

  • Maintenez la documentation en même temps que le code

La meilleure façon d’avoir une documentation à jour est de la modifier en même temps que le code, et non pas à la fin du développement lorsque vous êtes pressés de publier une nouvelle version de votre logiciel.

  • « Versionnez » la documentation avec le code

Puisque vous utilisez un gestionnaire de code source (GitMercurial par exemple) afin de garder une trace de toutes vos modifications, pourquoi ne pas utiliser cet outil pour votre documentation ?

Ainsi, pour chaque « commit » portant sur du code, vous pourrez inclure les changements de documentation.

  • Abordez aussi la sécurité dans votre documentation

N’oubliez pas d’envisager la dimension sécurité dans la documentation utilisateur ou développeur. Vous pouvez notamment documenter les différents choix de configuration de votre application, et expliquer quels sont les réglages les plus sécurisés.

Les mots clés associés à cet article