Quasiment tous les projets java utilisent ce principe.
Et python et les projets qui utilisent doxygen et julia et ocaml et golang...
Cela dit, avec asciidoctor par exemple, on devrait pouvoir externaliser cette documentation.
Ça ne fais pas la même chose. Tu ne peux associer cette documentation à ton code. Donc aucun éditeur ne pourra t'aider. C'est pas inutile pour autant, mais ce n'est pas la même chose.
Ça fait sens si on veut la traduire et même documenter à partir des tests, des exemples de code tiré du git, présent dans d'autres fichiers.
Tout à fait beaucoup font vraiment leur tambouille pour ça que ce soit avec de la doc inline ou des trucs comme asciidoctor. Il y a même un langage dont la doc inline peut contenir une portion de code qui sera exécutable, mais j'ai pas pu retrouver où j'avais vu ça.
Je veux bien documenter une classe, au dessus du code de celle-ci, car ça ne gêne pas la lecture du code.
La plupart des éditeurs permettent de la cacher et les linters te fournissent un minimum de vérification de la correspondance.
Par contre documenter toutes les méthodes est une perte de temps, surtout lorsque ça paraît triviale.
Je n'ai pas dû être claire. Il s'agit de documenter l'API. La complexité du code sous-jacent n'a rien à voir. Si ça peut être plus clair, imagine le cas d'une bibliothèque C ou C++ qui décrit ça avec doxygen dans ses entêtes. L'écriture de cette documentation peut être antérieure à l'écriture du code qui l'implémente. Par exemple tu peut aller jusqu'à indiquer la complexité de l'implémentation et c'est alors judicieux de documenter aussi ce qui te paraît trivial. C'est un contrat de l'API.
Ah et ça ça concerne l'API et non tout le code (à moins que tout ton code soit une API). Généralement une faible portion du code d'une bibliothèque fait partie de l'API, sinon ça devient complexe à maintenir. On peut voir un exemple avec rxjava pour une classe qui fait partie de l'API et une qui n'en fait pas parti.
La doc inline qui explique un passage complexe est bien sûr primordial.
Encore une fois ça n'a rien à voir. Documenter une API et commenter un code sont 2 choses qui n'ont rien à voir et sont régulièrement faites par des personnes différentes (c'est celui qui implémente qui documente son code alors que rien ne l'oblige pour la documentation d'une API).
Je trouve important de la doc non associée à l'API qui décrit plus les concepts et qui ne soit pas organisée par rapport au code, mais l'un empêche pas l'autre et ils ont des objectifs bien différents.
[^] # Re: No comment
Posté par barmic 🦦 . En réponse au journal Toileharicot 12 est dehors. Évalué à 6.
Et python et les projets qui utilisent doxygen et julia et ocaml et golang...
Ça ne fais pas la même chose. Tu ne peux associer cette documentation à ton code. Donc aucun éditeur ne pourra t'aider. C'est pas inutile pour autant, mais ce n'est pas la même chose.
Tout à fait beaucoup font vraiment leur tambouille pour ça que ce soit avec de la doc inline ou des trucs comme asciidoctor. Il y a même un langage dont la doc inline peut contenir une portion de code qui sera exécutable, mais j'ai pas pu retrouver où j'avais vu ça.
La plupart des éditeurs permettent de la cacher et les linters te fournissent un minimum de vérification de la correspondance.
Je n'ai pas dû être claire. Il s'agit de documenter l'API. La complexité du code sous-jacent n'a rien à voir. Si ça peut être plus clair, imagine le cas d'une bibliothèque C ou C++ qui décrit ça avec doxygen dans ses entêtes. L'écriture de cette documentation peut être antérieure à l'écriture du code qui l'implémente. Par exemple tu peut aller jusqu'à indiquer la complexité de l'implémentation et c'est alors judicieux de documenter aussi ce qui te paraît trivial. C'est un contrat de l'API.
Ah et ça ça concerne l'API et non tout le code (à moins que tout ton code soit une API). Généralement une faible portion du code d'une bibliothèque fait partie de l'API, sinon ça devient complexe à maintenir. On peut voir un exemple avec rxjava pour une classe qui fait partie de l'API et une qui n'en fait pas parti.
Encore une fois ça n'a rien à voir. Documenter une API et commenter un code sont 2 choses qui n'ont rien à voir et sont régulièrement faites par des personnes différentes (c'est celui qui implémente qui documente son code alors que rien ne l'oblige pour la documentation d'une API).
Je trouve important de la doc non associée à l'API qui décrit plus les concepts et qui ne soit pas organisée par rapport au code, mais l'un empêche pas l'autre et ils ont des objectifs bien différents.
https://linuxfr.org/users/barmic/journaux/y-en-a-marre-de-ce-gros-troll