Forum: Rails France Bonne pratiques commentaires/documentation de code

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!

Le 25/02/10 17:45, Julien Lestavel 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 Mougel
http://blog.shingara.fr/

Nicolas Jacobeus (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:

http://www.slideshare.net/Belighted/25-real-life-t...

--
Francois Stephany
http://agilitic.com

> 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 Lestavel 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

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 Belleville


2010/2/25 Francois Stephany <tulipe.moutarde@gmail.com>

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 Belleville <michel.bellevi...@gmail.com>

> http://www.slideshare.net/Belighted/25-real-life-t...

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,

Fernando Perez wrote:
>> http://www.slideshare.net/Belighted/25-real-life-t...

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)"

> 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).

--
francois.stephany@agilitic.com
http://www.agilitic.com
+32 (0)484/580.322