Je préfère prendre une bibliothèque moins bonne mais mieux documentée qu'un excellente sans document.
Si tu es capable d’utiliser celle qui est excellente il vaut mieux choisir celle-ci quitte à la documenter toi-même.
Pour une bibliothèque, qui n’a donc pas d’interface utilisateur, la doc peut en effet très bien se limiter à une courte introduction de deux lignes, typiquement dans un fichier README. Comme tu le dis il faut aussi connaître la licence et le langage ciblé. Sur ce point je dirais que si tu as téléchargé le code source, tu as déjà ces informations. Par exemple ici, rien qu’avec ce journal tu connais le langage et la licence est à deux clics d’ici... Ensuite, si chaque classe, chaque fonction, et, éventuellement, c’est bien sûr à éviter, chaque truc un peu tordu est documenté, ça suffit à utiliser le code source, à apprendre à s’en servir. L’utilisation d’un linter pour s’assurer qu’on a bien commenté chaque objets est pratique.
C’est sûr que parfois, le nom d’une fonction avec le nom de ses arguments ne peut pas être reformulé en anglais ou en une autre langue naturelle de manière plus précise, concise et pertinente :)
En Python je profite souvent du commentaire pour indiquer le type d’argument attendu ou le type retourné. Je ne considère pas qu’il soit souhaitable de préfixer tous ses identifiants avec leur type, mais c’est le genre d’info utile qui a bien sa place ici, juste à côté du code, à la ligne suivante... C’est mieux qu’au fin fond d’un wiki ou d’un document de traitement de texte... simplement à un autre endroit...
defdoThing(coquelets,jointerPlane):"""Do thing to coquelets with sharp jointer plane. (dict,int) = doThing(list,Tool)"""...
[^] # Re: Sans documentation ou tutoriel...
Posté par Marotte ⛧ . En réponse au journal Publication de bibliothèques c++ sous licence libre. Évalué à 3. Dernière modification le 16 février 2018 à 00:19.
Si tu es capable d’utiliser celle qui est excellente il vaut mieux choisir celle-ci quitte à la documenter toi-même.
Pour une bibliothèque, qui n’a donc pas d’interface utilisateur, la doc peut en effet très bien se limiter à une courte introduction de deux lignes, typiquement dans un fichier README. Comme tu le dis il faut aussi connaître la licence et le langage ciblé. Sur ce point je dirais que si tu as téléchargé le code source, tu as déjà ces informations. Par exemple ici, rien qu’avec ce journal tu connais le langage et la licence est à deux clics d’ici... Ensuite, si chaque classe, chaque fonction, et, éventuellement, c’est bien sûr à éviter, chaque truc un peu tordu est documenté, ça suffit à utiliser le code source, à apprendre à s’en servir. L’utilisation d’un linter pour s’assurer qu’on a bien commenté chaque objets est pratique.
C’est sûr que parfois, le nom d’une fonction avec le nom de ses arguments ne peut pas être reformulé en anglais ou en une autre langue naturelle de manière plus précise, concise et pertinente :)
En Python je profite souvent du commentaire pour indiquer le type d’argument attendu ou le type retourné. Je ne considère pas qu’il soit souhaitable de préfixer tous ses identifiants avec leur type, mais c’est le genre d’info utile qui a bien sa place ici, juste à côté du code, à la ligne suivante... C’est mieux qu’au fin fond d’un wiki ou d’un document de traitement de texte... simplement à un autre endroit...