Se servir de la documentation, une compétence vitale !

Un document technique

Pour être un bon développeur, il faut avoir pas mal de compétences. Savoir écrire du code, tester son logiciel, etc. Il y a en d’autres dont on ne précise pas  mais ont quand même une certaine importance. Le simple fait de savoir se servir d’une documentation est crucial, c’est automatique pour la grande majorité des développeurs. Mais pour ceux qui débute dans le monde de la programmation, ben ce n’est pas forcement évident ! Voyons comment se servir d’une documentation !

Une documentation pourquoi faire ?

Il existe plusieurs types de documentation dans le monde des programmes comme le manuel d’utilisation. Lorsque vous achetez un nouvel objet ou un logiciel, il y en a généralement un. Cela permet de prendre rapidement en main votre acquisition. Dans cet article, je parle de documents techniques pour les développeurs qui vont les aider à créer des programmes.

La documentation va donc expliquer toutes les possibilités qu’offre un langage de programmation ou une bibliothèque. Elle va donner des informations sur le fonctionnement des classes, fonctions et instructions qui existe.

  • Pour le cas des instructions qui sont présentes dans la documentation de langages de programmation, elle va nous dire comment les utiliser et ce qu’elles font.
  • Pour les fonctions et les méthodes, elle va expliquer ce qu’elles prennent en paramètre, ce qu’elles retournent et ce qu’elles font concrètement.
  • Enfin pour les classes, on a toutes les méthodes et tous les attributs qui sont expliqués. Elle nous donne également des informations sur quoi elle hérite et nous fournit des liens vers la documentation de ces parents.

La documentation dresse généralement une liste complète de ces éléments de façon à ce qu’on puisse naviguer facilement de page en page afin de trouver quelque chose d’intéressant. Cette liste se trouve soit en sommaire, soit sur un des côtés de la page.

En plus des détails, la documentation nous donne souvent des exemples concrets et directement testables de ce qu’elle explique.

Absolument tout est précisé ! Mais attention, son rôle est donné des informations sur l’utilisation de ces outils. Elle n’expliquera pas le fonctionnement interne d’une classe par exemple. Tous les éléments qui sont accessibles aux programmeurs s’appellent une API.

Une API (Application Programming Interface) est une interface de programmation d’application. Ce sont des services que des logiciels comme des librairies, offrent à d’autres logiciels par le biais de classes et de méthodes publiques.

Pour faire simple, la documentation est une énorme banque d’informations à consulter si besoin.

Créer sa propre documentation

Créer une documentation n’est pas indispensable pour des petits logiciels, tant que vous gardez un code source clair et commenté ça suffit amplement. Elle le devient par contre lorsque votre projet devient complexe et qu’une grande équipe travaille dessus ou alors que vous développez une librairie afin que d’autres personnes puissent s’en servir dans leur logiciel.

La documentation peut être faite « à la main » avec un logiciel de traitement de texte, mais peut aussi être créée automatiquement grâce à des outils comme javadoc ou doxygen. Ce sont des outils qui se basent sur les commentaires de fonction et de classes du code source pour générer ces documents. L’avantage d’un tel outil c’est que c’est simple et rapide. On fait une pierre deux coups, le code source est commenté, la documentation est crée.

Sites de documentation

Ici une petite liste des documentations en ligne qui existe. Attention, la majorité des sites sont en anglais !

Si vous avez déjà le nom d’une fonction ou d’une classe, tapez juste son nom sur Google ou dans la barre de recherche de la documentation. Vous tomberez directement sur la page qu’il vous faut. Sinon, baladez-vous dans la documentation de votre choix, vous apprendrez toujours quelque chose !

Partager l’article :
  •  
  •  
  •  
  •  
  •  
  •  
  •  
  •  
  •  

Laisser un commentaire

Votre adresse de messagerie ne sera pas publiée. Les champs obligatoires sont indiqués avec *

Ce site utilise Akismet pour réduire les indésirables. En savoir plus sur comment les données de vos commentaires sont utilisées.