Je te rejoins sur l'intérêt d'une doc meta et c'est ce que j'ai en tête quand je dis que je cherche une solution pour faciliter la compréhension du dépôt sans pour autant rédiger deux cent pages de doc. L'idée serait d'avoir une description générale du fonctionnement des modules, sans aller dans la description des détails dans le code.
Ce que nous avons supprimé ce sont les commentaires du type
/** The size */
std::size_t _size;
}; // class container
Et autres descriptions de classes et fonctions qui ne font que reformuler ce que dit le nom de la classe ou de la fonction. Ce genre de commentaire se trouve malheureusement assez facilement, même dans des projets de sources respectables (un exemple, un autre et il nous semble que cela est plus gênant qu'autre chose. Du coup le commentaire systématique de chaque identifiant, nous le faisions il y a quelques années et nous avons laissé tomber.
Là il n'y a pas de doc globale simplement parce qu'en pratique nous n'en avons pas besoin : tous les développeurs font les revues de tous les autres, y compris les nouveaux venus. Si nécessaire on échange sur les points peu clairs. À notre échelle ça suffit mais je suis bien conscient que ça ne suffit pas pour le grand public ou si tous nos développeurs partaient en même temps.
[^] # Re: Merci pour ce partage - mais la doc fouque
Posté par Julien Jorge (site web personnel) . En réponse au journal Publication de bibliothèques c++ sous licence libre. Évalué à 8.
Je te rejoins sur l'intérêt d'une doc meta et c'est ce que j'ai en tête quand je dis que je cherche une solution pour faciliter la compréhension du dépôt sans pour autant rédiger deux cent pages de doc. L'idée serait d'avoir une description générale du fonctionnement des modules, sans aller dans la description des détails dans le code.
Ce que nous avons supprimé ce sont les commentaires du type
Et autres descriptions de classes et fonctions qui ne font que reformuler ce que dit le nom de la classe ou de la fonction. Ce genre de commentaire se trouve malheureusement assez facilement, même dans des projets de sources respectables (un exemple, un autre et il nous semble que cela est plus gênant qu'autre chose. Du coup le commentaire systématique de chaque identifiant, nous le faisions il y a quelques années et nous avons laissé tomber.
Là il n'y a pas de doc globale simplement parce qu'en pratique nous n'en avons pas besoin : tous les développeurs font les revues de tous les autres, y compris les nouveaux venus. Si nécessaire on échange sur les points peu clairs. À notre échelle ça suffit mais je suis bien conscient que ça ne suffit pas pour le grand public ou si tous nos développeurs partaient en même temps.