Bonne pratiques commentaires/documentation de code

[julien]

Salut à tous,

Je vous sollicite pour un petit partage d’expérience concernant la
documentation du code (commentaires ou documents annexes). Avez-vous des
bonnes pratiques à recommander?

Pour être plus précis, j’aimerais instaurer des pratiques un peu plus
rigoureuses sur le sujet au sein de notre équipe de développement, afin
d’obtenir un code bien documenté et, chose importante, de manière
homogène (que les commentaires aient tous le même formalisme). Avez-vous
des conseils à ce sujet?

Les questions que je me pose sont :

• que documentez-vous? (tous les fichiers? toutes les méthodes?)
• comment documentez-vous? (avez-vous un modèle de commentaire? quelles
  informations gardez vous : auteur, date de dernière modif, description?
  utilisez-vous rdoc?..)

Je sais que Ruby a l’avantage d’être très intuitif, donc de nécessiter
moins de commentaires explicatifs, mais je pense qu’il ne nous en
dispense pas complétement…

Merci d’avance pour vos réponses!

[julien]

Le 25/02/10 17:45, Julien L. a écrit :

des conseils à ce sujet?

Merci d’avance pour vos réponses!

Personnellement ma meilleur documentation s’appelle Rspec ou Cucumber

1. m’oblige a tester mon code
2. Me liste facilement les fonctionnalités de mon code

Au niveau du code pur. J’avoue ne pas trop documenté. En effet,
documenter les méthodes du controller sont souvent inutile.

Le vrai truc a document est le code de librairie.

Dans les ressources que je peux te proposer, c’est un post de yannick

http://elsif.fr/le-code-et-les-commentaires

–
Cyril M.

Shingara - Actualité et News

[julien]

Nicolas J. (de Belighted) a fait une courte présentation de
quelques bonnes pratiques Rails au FOSDEM 2010.

Rien de bien nouveau pour les développeurs confirmés mais ça peut faire
du bien aux débutants/gens qui codent tout seul:

25 Real Life Tips In Ruby on Rails Development

–
Francois S.
http://agilitic.com

[julien]

Au niveau du code pur. J’avoue ne pas trop document�. En effet,
documenter les m�thodes du controller sont souvent inutile.
Oui enfin, parfois certaines méthodes avec des petites astuces peuvent
paraître très limpides dans quelques semaines, et là un petit
commentaire explicatif du pourquoi du comment aide bien.

Je me vois très mal étudier les méthodes Rails en lisant leurs tests.

[julien]

Mes 2 cents :

1. commencer par de très bons tests qui montrent bien ce que devrait
   faire le bidule, pas trop commentés
2. continuer avec une bonne grosse description dans le README ; elle
   devrait idéalement couvrir toute l’API dans ce qu’elle a de général,
   laisser
   les particularités ailleurs
3. pour chaque classe centrale, un petit pavé de description
   spécifique
   dans son fichier pour expliquer comment elle marche
4. donner une ligne de description minimum pour chaque méthode Ã
   exposer
   dans l’api, quand son nom ne rend pas son fonctionnement évident ; si
   les
   paramètres ne sont pas évidents, les expliquer
5. utiliser :nodoc: pour les méthodes dont le comportement est
   évident /
   hérité (ex: si une classe inclue Enumerable et qu’elle redéfinie
   quand même
   each pour qu’il fasse ce que l’on s’attend qu’il fasse, hop un petit
   :nodoc:
   pour éviter qu’elle n’encombre la doc inutilement, on n’est pas en
   Java)
6. de temps en temps un commentaire peut clarifier un code obscure
   dans
   une méthode, mais depuis que je code du Ruby j’ai rarement été dans
   une
   situation où c’était vraiment le cas (ou alors c’était un script de
   1000+
   lignes qui de toute façon mériterait d’être correctement factorisé /
   classifié)

De toute façon, il n’y a pas vraiment de ligne directrice stricte, donc
le
mieux c’est quand même une logique qui te convient et que tu suis.

Michel B.

2010/2/25 Francois S. [email protected]

[julien]

Julien L. wrote:

des conseils à ce sujet?

Merci d’avance pour vos réponses!

Salut,

pour ma part, j’essaye de :

• mettre quelques lignes de commentaires au début de chaque classe
• faire des méthodes courtes avec un nom relativement explicite
• faire peu de commentaires de manière générale
• mais expliquer le pourquoi pour les passages difficiles.

Et, j’évite de :

• commenter chaque méthode
• utiliser une syntaxe particulière (je ne me sers jamais de
  documentation générée)
• mettre des informations comme l’auteur ou la date de dernière
  modification (git, ou à défaut un autre scm, est là pour ça).

Ensuite, ça dépend fortement si le code est une application où
relativement peu de personnes vont avoir à naviguer dans le code, ou si
c’est un plugin destiné à être utilisé par un grand nombre de
développeurs. Dans le second cas, je vais essayer d’accompagner le code
d’une documentation de haut-niveau : README, howto sur un blog, etc.

++
Bruno

[julien]

aucun commentaire
ou alors une petite explication si vraiment, mais alors vraiment, la
methode le necessite

Le code doit etre assez explicite pour être comprehensible par un
autre développeur qui le lit pour la premiere fois.
Et quand il y a un commentaire surtout pas d’humour ou de commentaire
à la “cool”.
Alexis

On Feb 26, 8:35 pm, Michel B. [email protected]

[julien]

25 Real Life Tips In Ruby on Rails Development

Dans son slide #10, je cite: “Never call save/update in a hook!”

Que veut-il dire par là ? Que toute action save/update doit se faire au
niveau du controlleur?

C’est justement une question que je me posais et une précision
m’intéresserais.

Salutations,

[julien]

Dans son slide #10, je cite: “Never call save/update in a hook!”
Que veut-il dire par là? Que toute action save/update doit se faire au
niveau du controlleur?

A vue de nez je dirais que c’est simplement pour ne pas tomber dans une
boucle infinie (imagine un save/update dans un after_save).

–
[email protected]
http://www.agilitic.com
+32 (0)484/580.322

[julien]

Fernando P. wrote:

25 Real Life Tips In Ruby on Rails Development

Pardon, une autre précision également. Dans le slide 19/29 (#16), il
parle de “Only call a Model once in each controller method (besides
save/update)”

Est-ce que cela signifie qu’on ne doit pas faire la chose suivante:

@user = User.find(…)
@user.mark_as_supplier
@user.notify_customers
@user.send_registration_email

Cette question est d’ailleurs un peu liée à ma précédente. A noter que
dans User#mark_as_supplier et User#notify_customers il y aurait des
opérations d’update (par exemple).

PS: dans mon message précédent, il fallait lire “dans son slide #7
(10/29)”