Documentation du code: publique ou non publique?

Je fais partie de ces développeurs qui pensent que le code écrit doit être explicite et se lire comme un livre.

TOUTEFOIS, lors du développement de code de bibliothèque pour d'autres personnes, j'essaie de mettre autant de documentation que possible dans les fichiers d'en-tête; ce qui soulève la question: la documentation de méthodes non publiques en vaut-elle la peine? Ils ne les utiliseront pas directement, en fait, ils ne le peuvent pas. En même temps, si je distribue le code brut (quoique à contrecœur), ces méthodes non publiques seront visibles et devront peut-être être expliquées.

À la recherche de quelques normes et pratiques que vous voyez ou utilisez tous dans vos voyages.

Je n'envisagerais jamais d'omettre la documentation pour les internes simplement parce qu'un "utilisateur final" ne les utilisera pas; la maintenance du code est une raison plus que suffisante pour inclure des commentaires de documentation pour tous les composants, en particulier pour les composants internes qui ont tendance à être la partie la plus complexe (et souvent changeante).

Cela dit, il peut être justifié de les restreindre au code source non en-tête (plutôt que documenté publiquement), afin de maintenir l'abstraction.

Tout cela est plutôt subjectif, faites attention.

Ok, j'ajoute ma façon de commenter / documenter aussi à l'image pour la variété. La raison est que j'évite de décrire des fonctions ou des fonctions membres qui ne sont déclarées que dans l'en-tête. D'une part, je crains d'ajouter trop de bruit à l'en-tête. D'autre part, la documentation ainsi que la définition sont plus faciles à faire correspondre par le responsable. Doxygen ne se soucie pas de toute façon et peut filtrer les soldats si nécessaire.

En-tête de classe:

• en-têtes inclus (pourquoi)
• définitions de classe toujours (but et responsabilités)
• les fonctions virtuelles pures toujours (contrat complet)
• les fonctions en ligne à moins que des getters explicites
• autres types déclarés, à moins qu'ils ne soient explicites
• membres de données statiques (pourquoi)
• autres membres de données à moins qu'ils ne soient explicites
• les macros éventuelles (contrat et pourquoi)

Code d'implémentation en classe:

• déclarations locales de la même manière que dans l'en-tête
• définitions des fonctions toujours (contrat complet)
• définitions de fonctions membres toujours (contrat complet ou référence à la racine du remplacement virtuel)
• variables statiques définies le cas échéant (objectif pourquoi)

Dans l'en-tête du modèle:

• ce qui précède a fusionné et
• types appropriés / inappropriés pour les arguments de modèle et
• dans quelle mesure l'adéquation est détectée statiquement

Au private:début de la section privée se trouve toute la documentation dont les utilisateurs ont besoin.

La documentation en vaut la peine tous les jours, elle permet d'expliquer brièvement les cas d'utilisation et les histoires. Bien que le code soit explicite, il ne peut pas expliquer l'entreprise aussi facilement que quelques lignes de narration. Le code obligerait certainement l'utilisateur à suivre la logique en plus de comprendre ce qui se passe. :-) Mes 2 cents ...

Absolument!

Ce code devrait être auto-documenté est un slogan pour vivre. Pourtant, j'irais jusqu'à dire que le code privé a besoin d'autant de documentation, sinon plus, que de code public, car c'est généralement ici que la plupart des hypothèses ont généralement lieu, simplement parce que le codeur suppose qu'il restera dans le noir . Donc, quelques mois plus tard, lorsqu'un bogue arrive, vous passerez du temps à essayer de vous rappeler quelle était l'idée derrière le code (peut-être vous-même) écrit.

La documentation ne devrait pas être là comme un beau cadeau pour les autres. La documentation, sous tous ses aspects (noms de variables bien choisis, noms de classe auto-documentés, code bien organisé, méthodes correctement segmentées, etc.) est un cadeau pour tous ceux qui peuvent entrer en contact avec votre code, vous y compris.