Ca, ca reste a prouver. Je préfère typiquement du code type en python par exemple a des docstrings avec la liste des parametres qui ne seront pas a jour un jour ou l'autre.
Pas tant que ça, cela dépends, je donne un exemple.
Nous avons un dépôt, avec une collection de rôles Ansible, chacun avec un README in Markdown.
Un des "hooks pre-push" de Git, est de vérifier qu'aucun fichier dans le rôle n'est plus récent que le fichier readme. Lorsque c'est le cas, le push est refusé.
Les fichiers "readme" contiennent ce que le code ne peut pas contenir convenablement : Une vue d'ensemble (e.g. mermaid / svg), les variables Ansible à définir, optionnelles ou non, des liens vers des sites internet, etc.
Lors de l'intégration continue (Jenkins out Gitlab), une des tâches assemble tous les fichiers readme, dans un site readthedocs. Au final, c'est très pratique.
Alors oui, la doc qui répète le code, c'est inutile, mais la doc qui donne une vue d'ensemble du code, c'est pratique.
[^] # Re: Complètement crétin !
Posté par Andre Rodier (site web personnel) . En réponse au journal Comment briller auprès de la gent féminine dans « le monde de la tech ». Évalué à 6.
Pas tant que ça, cela dépends, je donne un exemple.
Nous avons un dépôt, avec une collection de rôles Ansible, chacun avec un README in Markdown.
Lors de l'intégration continue (Jenkins out Gitlab), une des tâches assemble tous les fichiers readme, dans un site readthedocs. Au final, c'est très pratique.
Alors oui, la doc qui répète le code, c'est inutile, mais la doc qui donne une vue d'ensemble du code, c'est pratique.