l'Impact de la documentation sur un logiciel
La documentation des logiciels est essentielle pour maintenir votre projet de logiciel sur la bonne voie.
Imaginez que vous commencez à utiliser un nouveau logiciel, mais que vous ne savez pas comment utiliser le logiciel et ses différents aspects.
En ce qui concerne les jeunes développeurs, il n'y a aucun moyen d'apprendre le fonctionnement du code à moins que quelqu'un d'autre ne le leur explique ou qu'ils aient quelque chose à quoi se référer. C'est difficile à imaginer, pourtant cela pourrait arriver. La documentation existe pour une raison : pour que les gens sachent où ils s'en vont.
La documentation des programmes informatiques consiste généralement en des descriptions textuelles des fonctionnalités incluses dans le programme et en des illustrations montrant comment elles se présentent lorsqu'elles sont utilisées.
Documentation des logiciels
La documentation des logiciels est essentielle pour maintenir votre projet de logiciel sur la bonne voie.
Voyons comment la documentation du logiciel peut profiter à votre projet :
Lisibilité du projet De nos jours, avec le grand nombre de langages ou de frameworks, il devient difficile et fastidieux, même pour un programmeur de niveau avancé, de connaître les composants internes d'un projet logiciel. La documentation sert de guide pour la lecture du projet.
Extensibilité du projet : Même un seul développeur peut travailler sur un petit projet, cependant pour faire évoluer ce projet vers les niveaux de Netflix, Amazon, Telegram, etc. Et si chaque membre de l'équipe doit parcourir le code pour contribuer, cela nuit à l'évolutivité. C'est pourquoi la documentation est nécessaire.
Ces énumérations ne sont pas exhaustives, essayons de comprendre maintenant en profondeur les subtilités de la documentation des logiciels.
- Lorsque vous documentez le code, la maintenance du code est plus facile.
- La documentation aide les autres à apprendre comment travailler avec le code et les fonctions fournis par le développeur.
- Elle peut également contribuer à améliorer la qualité générale du code, car elle fournit plus de détails sur chaque partie du programme.
- Elle aide les gens à mieux comprendre comment travailler avec votre logiciel. La documentation peut être utile en facilitant la tâche des personnes susceptibles de vous aider par la suite.
- En partageant nos connaissances, nous nous assurons que tous les autres comprennent quelque chose qu'ils ne savaient pas auparavant.
- La documentation permet de s'assurer que tout le monde comprend ce qui se passe.
- Toute personne qui lit la documentation peut facilement voir d'où vient chaque code et quelle partie de l'application l'utilise.
- Elle permet d'économiser du temps et des efforts en évitant de devoir former de nouveaux employés lorsque l'un d'eux quitte son poste.
Pour en savoir plus sur le travail en équipe je vous recommande d'écouter notre podcast qui en parle en cliquant ici
Un bon code doit se documenter seul
Un bon code, autodocumenté (Self-documenting code en anglais) est en principe écrit à l'aide de noms lisibles par l'homme.
Chaque nom d'une variable ou d'une fonction doit réellement refléter la tâche effectuée par celle-ci.
Le code doit également avoir une structure claire et nette afin qu'un lecteur humain puisse facilement comprendre l'algorithme utilisé.
Prenons le cas de cet exemple pris sur Wikipédia
size_t count_alphabetic_chars(const char *text) {
if (text == NULL)
return 0;
size_t count = 0;
while (*text != '\0')
{
if (is_alphabetic(*text))
count++;
text++;
}
return count;
}Vous ne connaissez pas la personne qui a écrit ce code, mais juste en le lisant vous comprenez la tâche qu'il est sensé réalisée
pour écrire un code facilement compréhensible vous devez avoir :
- Une uniformité dans vos conventions de nommage
- une consistance (ou cohérence) dans votre manière de faire les chose
Épilogue
La documentation des projets logiciels présente ses propres défis, des défis que vous devez affronter, car cette dernière a un impact conséquent sur la lisibilité de votre code.
En programmation informatique, la lisibilité désigne la facilité avec laquelle un lecteur humain peut comprendre l'objectif, le flux de contrôle et le fonctionnement du code source. Elle affecte les aspects de la qualité ci-dessus, notamment la portabilité, la facilité d'utilisation et, surtout, la maintenabilité.
La lisibilité est importante, car les programmeurs passent la majorité de leur temps à lire, à essayer de comprendre et à modifier le code source existant, plutôt qu'à écrire un nouveau code source. Un code illisible est souvent source de bogues, d'inefficacité et de duplication du code. Une étude a révélé que quelques transformations simples de lisibilité permettaient de raccourcir le code et de réduire considérablement le temps nécessaire à sa compréhension.