Mais pourquoi ne pas placer la documentation au plus près du code. Voire dedans, comme Python le permet —avec même la notion de références croisées, même inter-projets.
Par ce que la notion de documentation est très dépendante des projets. Ton idée marche pour les libs et uniquement les libs.
Autrement je te rejoins que si on ne distingue pas parfaitement 3/4 types de documentations on parle de tout et n'importe quoi et on fait n'importe quoi:
Les commentaires: Ils sont là pour aider à lire le code. Leur seule raison d'exister est "pourquoi" et l'intention. Par exemple, ca serait domage de laisser réintroduire des bugs dans une code base qui a été testé pendant des années par ce qu'on n'indique pourquoi on fait ce foutu truc (ah oui c'était une bugfix suite à un BR ouups).
Les documents de design: Selon la taille du projet ils sont à écrire ou non. Ca peut aller de 10 lignes dans un readme, à pleins de page pour permettre de comprendre le design général et comment s'y retrouver dans ces 300 modules. Les règles générale, les règles d'interactions etc.
La documentation des API: La encore selon ce sur quoi on bosse l'interet varie. Toute API publique doit évidement être parfaitement documentée. Pour les API internes c'est à choisir. Ecrire de la bonne documentation d'API est très couteux, et je constate que si c'est pour de l'interne je n'investi pas assez et donc qu'elle ne sert à rien car extremement redondante avec le code (typage static évidement)
La documentation utilisateur: La encore il faut voir en fonction de son produit. Dans la plupart des cas on essayera de faire léger et concis.
Dans tout les cas celui qui explique que le premier type ne sert à rien est un idiot avec une bonne mémoire qui bosse tout seul et n'a jamais travaillé sur autre chose que son code. Je ne vois pas d'autre explication.
Par contre il est vrai aussi qu'il faut se forcer pour que son code ait le moins besoin possible d'être commenté. Ca indique qu'il y a le moins de truc chelous ou difficile à intuiter dans le code et l'algo.
[^] # Re: /* commentaire ou documentation inline ? */
Posté par ckyl . En réponse au journal To comment or not to comment. That is the question.. Évalué à 7.
Par ce que la notion de documentation est très dépendante des projets. Ton idée marche pour les libs et uniquement les libs.
Autrement je te rejoins que si on ne distingue pas parfaitement 3/4 types de documentations on parle de tout et n'importe quoi et on fait n'importe quoi:
Dans tout les cas celui qui explique que le premier type ne sert à rien est un idiot avec une bonne mémoire qui bosse tout seul et n'a jamais travaillé sur autre chose que son code. Je ne vois pas d'autre explication.
Par contre il est vrai aussi qu'il faut se forcer pour que son code ait le moins besoin possible d'être commenté. Ca indique qu'il y a le moins de truc chelous ou difficile à intuiter dans le code et l'algo.