Bonnes pratiques documentation

[JB]

Cet échange est lancé suite à une question sur le forum.

Comment documentez-vous vos VIs et CTLs ?

Quelles sont vos bonnes pratiques ?

[JB]

Voici ma manière habituelle :

• Description la plus concise possible du VI.
• Deux lignes vides.
• Description des entrées selon leur ordre sur le connecteur. Ligne vide entre chacune.
• Deux lignes vides.
• Description des sorties (même format que pour les entrées).
• Deux lignes vides.
• Nom.
• Entreprise.
• Date.

A moins d'un comportement particulier, je renonce à décrire "error in" et "error out".

Les noms des entrées et sorties (et parfois d'autres informations importantes) sont mis en gras. (<B></B> pour ceux qui ne connaîtrait pas)

AUCUN de mes VIs n'échappe à la documentation.

Une image parlant mieux que mille mots, voici un exemple :

PS : Je suis très intéressé par VOS bonnes pratiques qui me permettront certainement d'améliorer les miennes.

[Eric.M]

Je suis un bien mauvais documentariste de VI pour les VIs d'un projet à vocation exe/installeur, je décris peu dans les propriétés, et beaucoup dans le diagramme. Dès que mes VIs ont vocation à faire partie d'une API, ce n'est plus la même histoire, et je me retrouve sensiblement avec le même schéma : description, puis entrées/sorties (en n'oubliant pas les valeurs par défaut).

Par contre, j'utilise assez volontiers les outils de documentation disponibles (assez récemment) pour avoir un rendu plus rapide et plus pro :

https://decibel.ni.com/content/groups/labview-add-on-dev-center/blog/2011/07/28/vi-documentation-too...

Cdt

--Eric

[A._Dek...]

Bonjour,

En plus de la documentation traditionnelles des VI (comme exposé ici), j'utilise aussi maintenant les "sub-diagram labels" des structures. Ca evite les blocs texte qui se baladent un peu partout dans le code, et m'oblige à réfléchir à un commentaire systèmatiquement (dans options utilisateurs, block diagram, subdiagram labels visible by default)...

Pour une interface utilisateur, j'utilise aussi les "tips" et l'aide contextuelle des objets commandes de la face avant (et parfois aussi des indicateurs), pour aider l'utilisateur à comprendre l'usage de l'objet.

Cordialement,

Adeline.

[ouadji]

JB ...

pourquoi mets-tu l'empreinte de ton pouce au bas de la doc ? comprends pas !

ok .... 

[JB]

---

ouadji a écrit :

JB ...

pourquoi mets-tu l'empreinte de ton pouce au bas de la doc ? comprends pas !

ok .... 

---

Ce n'est pas mon pouce mais ma langue.
Un code aussi léché mérite bien une telle signature !

[JB]

Si ma question portait initialement sur la documentation apparaissant dans le "Context Help" d'un VI ou CTL, il est très intéressant de l'élargir à la documentation en général de notre code LV.

• diagramme (comme vient de le faire Adeline)
• face-avant (Adeline encore)
• icône
• documents externes (documentez-vous par exemple la structure générale d'une application et si oui comment ?)
• ...

Merci donc à vous tous d'alimenter cette discussion pour en faire un partage riche et instructif.

[JB]

Voici mes habitudes pour les icônes.

Comme je documente CHACUN de mes VIs et CTL, CHACUN se voit également habillé d'un icône compréhensible et dont le but premier est de faciliter la lisibilité du code.

En règle générale :

• Barre de titre indiquant la catégorie du VI ou CTL. Il s'agit de templates partagés par tous les développeurs de notre entreprise.
• Des couleurs d'arrière-plan différentes sont utilisées pour distinguer VIs et CTL  (VI invisible = blanc, VI interface utilisateur = jaune et CTL = noir).
• Les VIs réentrants sont marqués par un "R" dans le coin supérieur droit de la barre de titre.
• Les VIs appelés dynamiquement recoivent un "D" à cet emplacement.
• Je vous laisse deviner pour un VI réentrant appelé dynamiquement...

A l'image des templates, nous partageons également une librairie de glyphs complétée au cours des projets. Les marques des VIs réentrants et dynamiques en font par exemple partie.

Dans l'exemple ci-dessus, l'icône montre immédiatement qu'il s'agit d'un VI réentrant de la famille AI (entrée analogique) avec une attente.

[A._Dek...]

Je suis impressionnée par toutes ses règles... surtout pour les icônes !!

Par contre, je suis étonnée par l'utilisation du francais : on m'a toujours conseillé de documenter tout en anglais...

Les outils proposés par Eric sont bien sympas, je les intègre de suite. Enfin un moyen rapide de documenter tous les VI et de vérifier qu'aucun n'est passé à la trappe...

Adeline.

[JB]

Dans la pratique, ces quelques règles (ou plutôt habitudes) pour les icônes ne sont vraiment pas contraignantes.

Une fois que les librairies de templates et de glyphs existent (complétées au fil des projets), ces habitudes diminuent le temps pour générer les icônes tout en améliorant indiscutablement la lisibilité du code.

Etant donné que nos projets sont exclusivement pour un usage interne et que tous nos développeurs parlent la langue de Molière, nous n'avons aucun avantage à documenter en anglais. Mais il est bien évident que l'anglais serait plus universel et donc à conseiller de manière générale.