Julien Lestavel wrote: > 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!
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 -- Vous avez reçu ce message, car vous êtes abonné au groupe "Railsfrance" de Google Groups. Pour transmettre des messages à ce groupe, envoyez un e-mail à l'adresse [email protected] Pour résilier votre abonnement envoyez un e-mail à l'adresse [email protected]
