Discussion :

[adel.87]

bonjour à tout le monde je voudrais savoir quel sont les règles pour bien documenter son code


merci

[Garulfo]

bonjour à tout le monde je voudrais savoir quel sont les règles pour bien documenter son code


merci

Être clair, précis, uniforme (toujours les mêmes « habitudes ») et ne pas faire de mise en forme qui ne serait pas maintenable facilement.

Après le reste ça dépend de beaucoup de choses, dont le langage, les outils utilisés et les habitudes d'où tu es.

[Phelim]

Une des regles que je considere comme primordial, surtout quand on travaille seul :
- Ecrire les commentaires avant le code. Directement après avoir codé, on a la fausse sensation que tout est compréhensible dans notre code.

[bruno_pages]

Une des regles que je considere comme primordial, surtout quand on travaille seul :
- Ecrire les commentaires avant le code. Directement après avoir codé, on a la fausse sensation que tout est compréhensible dans notre code.

dans ce cas il ne s'agit pas de commentaires, mais d'analyse ... ce qui n'est pas la même chose

ce n'est pas parce que l'on a fait une analyse préalable (via UML ou non) qu'il ne faut pas commenter, ces commentaire étant alors dans le code, y compris à l'intérieur du corps des opération/fonctions ce qui dans ce cas ne peut pas être fait avant que celui-ci n'existe

la seule règle à respecter : que le commentaire ai un sens, qu'il apporte vraiment quelque chose c.a.d. des informations sémantiques et ne soit surtout pas un pseudo code ou une simple reprise de ce qui est écrit dans le langage de prog utilisé. Bref par exemple inutile de dire quels sont les types des arguments d'une opération/fonction, on le voit par ailleurs très bien dans le code, sauf s'il y a une génération automatique de doc utilisant ce genre d'info et n'étant pas capable de le faire à partir du code lui-même.

[whitespirit]

Bref par exemple inutile de dire quels sont les types des arguments d'une opération/fonction, on le voit par ailleurs très bien dans le code, sauf s'il y a une génération automatique de doc utilisant ce genre d'info et n'étant pas capable de le faire à partir du code lui-même.

Tout dépend du langage que tu utilises. En ce moment, je suis en PHP et tu ne définis pas de type de variable que ce soit dans le code ou dans les paramètres de fonctions (si tu ne connais pas le php, ca parait vachement bourrin - d'ailleurs pour faire cette remarque évidente je suis sûr que tu programme dans un langage tel que C++/JAVA). Donc pour comprendre un code que tu as écris, tu peux t'en sortir, mais par exemple, j'utilise un framework et heureusement que les paramètres IN/OUT sont documentés sinon j'aurai perdu un temps fou à comprendre le type de paramètre attendu et d'ailleurs, je n'aurai pas utilisé le framework. Ensuite, comme tu l'as dit, le générateur de documentation s'en sert pour créer la documentation.

[_skip]

Voici les règles que j'ai forcées dans mon entreprise :

La documentation des méthodes et classes se fait avec les tags standards pour la génération automatique et la prise en charge de l'intellisense.

La documentation d'une méthode doit inclure :
-Un descriptif de son utilité
-l'utilité de chaque paramètre et l'acceptation ou non de la valeur null.
-Une documentation des exceptions raisonnablement possibles.

Pas de préfixage des types primitifs, seuls les composants UI doivent être préfixés.

Par ailleurs, pour ce qui est de la véritable documentation, celle-ci n'est pas faite dans le code. On tâche de décrire dans des documents à part les solutions utilisées pour répondre aux problématiques métier, quelle manière de travailler on a choisie et pourquoi les autres ne fonctionnaient pas.
J'aimerai qu'à terme, nous fassions cela sur un wiki.

[whitespirit]

A savoir qu'il existe des scripts qui créé une documentation technique (api) en fonction des commentaires que tu as utilisés dans ton code. Chaque script de documentation (phpdocumentor en php, en java je ne sais plus, etc. pour chaque langage).

Donc dans un premier temps, regarde quels sont les documentors de code pour ton langage. Si tu utilises un éditeur particulier regarde s'il ne gère pas un de ces outils.

Suivant le type de documentor que tu utilises la syntaxe des commentaires va changer. Par exemple pour décrire une classe

Code :

Sélectionner tout - Visualiser dans une fenêtre à part

1
2
3
4
5
6
7
8
9
10
/**
  * Nom de classe
  *
  * Description
  *
  * @version 1.0
  * @author Moi
  * @package ...
  * @copyright ...
  */

C'est un exemple avec phpDocumentor mais tu n'es pas obligé de mettre toutes les variables @.

Idem pour chaque variable que tu déclares dans une classe

Code :

Sélectionner tout - Visualiser dans une fenêtre à part

1
2
3
4
5
    /**
     * Decorators for rendering
     * @var array
     */
    protected $_decorators = array();

Et le plus important (à mon sens), c'est la documentation des fonctions ou tu indiques clairement :

Code :

Sélectionner tout - Visualiser dans une fenêtre à part

1
2
3
4
5
6
7
    /**
     * Description de la fonction
     * 
     * @param  array $options description du paramètre d'entrée
     * @return booléen description de la variable de retour
     */
    public function setOptions(array $options)

Voilà, en gros si tu documentes tes classes, fonctions et variables de classes de cette façon, c'est extraordinaire.

Le reste, c'est du bon sens : une bonne arborescence des répertoires sur ton disque, des noms de fonctions/variables/classe clair. Par exemple, je mets toujours le type d'un attribut devant une variable : str_string, dt_date, tab_tableau, table_table... Idem pour les fonctions : les selecteurs commencent par SetNom(), etc, Get(), Is_Fct (une fonction qui retourne 1 ou 0)...C'est plus long à écrire mais quand tu repasses sur ton code, c'est plus facile à comprendre. Bien-sûr il faut bien indenter ton code avec la touche TAB, et mettre des commentaires (par exemple je commence toujours mes commentaires par //-- comment --//. De cette façon si j'ai récupéré du code, je vois tout de suite ce que j'ai commenté des commentaires existants).. Tu remarqueras que dans l'exemple ci-dessus, je préfixe mais attributs privés ou protégés par un underscore '_'. Bon souvent ça ne me sert pas à grand chose car le code que j'écris est très court.

Voilà, c'est ma façon de garder un code propre. Il n'y a pas vraiment de règle, mais tu as bien raison de te poser cette question. Ne jamais oublier qu'un autre codeur devra certainement utiliser tes classes, il faudra trouver facilement le type de paramètre d'entrée d'une fonction, les variables privés...

[SaintAmand]

Pour compléter ce qui a été écrit précédemment:
- Eviter de paraphraser le code: du genre le très classique

Code :

Sélectionner tout - Visualiser dans une fenêtre à part

1
2
i++; /* Incrémente i de 1

- Si vous utilisez un algorithme particulier (recherche de motif, ...), l'indiqué. Ajouter une référence vers un article ou un livre, si cet algorithme n'est pas censé être connu de ceux qui auront à vous lire.
- Les commentaires dans le coeur même du code son rarement nécessaire. Si cela vous parait le cas, alors il est probable que le code n'est pas propre ou utilise des «astuces». Dans ce cas mieux vaut réécrire ce code et éviter ces astuces qui ne servent qu'à satisfaire l'égo du développeur (sauf cas particulier bien entendu).
- Ecrire des tests unitaires. En autres, ils constituent une source de documentation inestimable puisqu'ils montrent comment utiliser votre code.
- Utiliser des outils de génération de documentation comme Doxygen, PerlDoc, ...

[Nip]

Pour compléter ce qui a été écrit précédemment:
- Eviter de paraphraser le code: du genre le très classique

Code :

Sélectionner tout - Visualiser dans une fenêtre à part

1
2
i++; /* Incrémente i de 1

- Si vous utilisez un algorithme particulier (recherche de motif, ...), l'indiqué. Ajouter une référence vers un article ou un livre, si cet algorithme n'est pas censé être connu de ceux qui auront à vous lire.
- Les commentaires dans le coeur même du code son rarement nécessaire. Si cela vous parait le cas, alors il est probable que le code n'est pas propre ou utilise des «astuces». Dans ce cas mieux vaut réécrire ce code et éviter ces astuces qui ne servent qu'à satisfaire l'égo du développeur (sauf cas particulier bien entendu).
- Ecrire des tests unitaires. En autres, ils constituent une source de documentation inestimable puisqu'ils montrent comment utiliser votre code.
- Utiliser des outils de génération de documentation comme Doxygen, PerlDoc, ...

Pas grand chose a ajouter. Si vous eprouvez le besoin d'ajouter des commentaires au sein de votre code, et a l'exception rare de certains algorithmes exotiques, c'est que votre code est mal ecrit.

[Davidbrcz]

Nip >> Le code auto-commenté car tellement il est bien écrit c'est vrai seulement pour la personne qui à codé le logiciel.

Car essaye de rentrer dans un logiciel externe où il y a 2 lignes de coms par fichier et tu verra que ce n'est pas si facile et ques les commentaires ne sont superflus même si le code est super. Et puis les coms permettent de s'y retrouver si on lâche le logiciel pendant un bout de temps.

[_skip]

Ca dépend de chacun mais personnellement, ce que mon oeil voit en premier lors de la relecture d'une fonction ce sont les commentaires. Donc pour moi un code sans commentaires c'est inconcevable pour la maintenance.

On peut sans doute s'interroger sur la pertinence du contenu des commentaires, mais sur leur nécessité elle-même là j'ai du mal à imaginer.

[_vince_]

Un petit bemol au commentaires dans le code: Les developeurs ont tendance a ne pas mettre a jour les commentaires en meme temps que le code qui va avec. Donc, mefiance... Par exemple, pour dire qu'un angle doit etre compris entre 0 et 360 degres, il vaut mieux une assertion qu'un commentaire.

Peut etre que le meilleur test pour savoir si le code est bien commente et bien ecrit est de le faire lire a un collegue ???

[Nip]

Nip >> Le code auto-commenté car tellement il est bien écrit c'est vrai seulement pour la personne qui à codé le logiciel.
. [...] Et puis les coms permettent de s'y retrouver si on lâche le logiciel pendant un bout de temps.

Mon commentaire allait en complement de celui de SaintAmand.

Compter sur les commentaires pour "s'y retrouver" apres un certain temps est un leurre. Les commentaires sont au mieux totalement inutiles et au pire ne sont pas a jour et/ou masquent la complexite de la partie commentee, parce que les "astuces" pullulent ou parce que la partie du code en question a tellement ete modifiee qu'elle en a perdu son sens initial.
La documentation avant code (j'inclus les tests unitaires qui sont de la documentation du code par le code), est le seul moyen fiable de s'y retrouver apres un certain temps et dans le cadre de code herite, le TDD permet a coup sur de garder un code clair et commente:
-parce que les tests passent au rouge si la classe/methode est modifiee trop en profondeur.
-parce que il est necessaire d'ecrire de nouveaux tests pour toute nouvelle fonctionnalitee.

Abandonnez les commentaires qui sont par essence totalement inmaintenables et passez aux test unitaires.

[whitespirit]

Je suis d'accord avec ce que tu as écris Nip et j'en prends bien note. Cependant

Abandonnez les commentaires qui sont par essence totalement inmaintenables et passez aux test unitaires.

ce n'est pas toujours possible de placer des test unitaires car ce que je développe (par exemple) est basé sur une architecture assez complexe : seules, les classes développées sont inexploitables. Dans un tel cas, quelle solution préconises-tu ?