Où mettre des commentaires documentaires?

Question

Très courte question: lors de la documentation du code Delphi (pour permettre à un outil externe de générer une documentation HTML (Doc-o-matic dans l'exemple concret)), mettez-vous les commentaires dans l'interface ou dans la mise en oeuvre section? Ce qui me plait dans la deuxième approche, c'est que la partie d'interface d'une classe reste propre et compacte et que les commentaires de documentation fonctionnent comme des séparateurs entre les fonctions de la section d'implémentation. D'autre part, Doc-o-matic semble avoir des problèmes de temps en temps lorsque je mets les commentaires de documentation dans la partie implémentation.

Que préférez-vous?

Answer 1

Il me semble qu'il serait préférable de mettre la documentation à côté de l'implémentation. La mise en œuvre est celle où vous êtes le plus susceptible d'apporter des modifications au code, et lorsque vous modifiez le code, vous devez consulter la documentation pour vous assurer qu'elle est toujours exacte, de sorte que vous pouvez également avoir les deux à proximité.

Olaf mentions y compris une description à l'interface, et vous demandez comment le générateur de documentation choisit quels commentaires utiliser. Une solution simple consiste à ne pas utiliser le format de commentaire spécial du générateur de documentation dans l'interface. Il doit ignorer ces commentaires comme étant des commentaires ordinaires sans documentation, de sorte que les commentaires de l'implémentation seront les seuls à être utilisés par le générateur. Ou vous pouvez mettre une brève description à l'interface et une longue description dans l'implémentation, et le générateur peut utiliser celui qui est le plus approprié pour le contexte (par exemple, une liste de toutes les méthodes avec des descriptions d'une seule ligne). une seule méthode).

SrbShell suggests mettre la documentation dans l'interface, et il est certainement d'avoir pratique tout à proximité, lorsqu'ils ne sont pas en utilisant un générateur de documentation. Mais cela devient beaucoup moins important quand vous avez un programme qui recueille de la documentation à partir de votre code et met tout cela ensemble. Dans ce cas, on s'attend à ce que vous soyez en utilisant également la documentation générée. Lorsque vous avez préparé la documentation, reportez-vous à celle-ci au lieu de devoir trouver la documentation dans le code. L'EDI peut même être configuré pour afficher les descriptions dans une fenêtre pop-up, de sorte que vous n'avez pas à le regarder dans un endroit séparé la plupart du temps.

J'ai parlé de ce que je vois comme le mode "idéal". Si votre outil particulier ne rend plus cette stratégie, alors adaptez-la à l'outil ou trouvez un outil différent.

Answer 2

Je préfère documenter le code dans la partie implémentation qui donne beaucoup de visibilité et de facilité à comprendre.

Answer 3

J'ai mis des commentaires "Résumé" dans l'interface, et la description complète, les paramètres etc. dans la partie implémentation. De cette façon, vous pouvez regarder l'interface d'une unité/classe et vous voyez immédiatement ce qu'il fait - sans pollution ...

Answer 4

J'ajoute un commentaire récapitulatif d'une ligne à la section d'interface et écris les commentaires détaillés dans la section d'implémentation. BTW, j'utilise Doc-O-Matic, et cela fonctionne très bien avec les commentaires dans la section de mise en œuvre. Quels sont les problèmes auxquels vous êtes confrontés lorsque vous écrivez les commentaires dans la section de mise en œuvre?

Answer 5

Je préfère placer ma documentation dans l'interface AVANT l'objet pour expliquer les problèmes de conception, le lien vers la documentation de conception, ou d'autres choses que l'utilisateur de la classe d'objet devrait connaître.Pour les méthodes, je les documente séparément et individuellement dans la section de mise en œuvre, immédiatement après la déclaration, mais avant le début. L'en-tête de chaque unité peut contenir une section notes de publication/historique juste après le nom de l'unité.

En général, mon bloc de commentaire de la méthode se présente comme suit (via des modèles):

{==============================================================================} 
Procedure Form1.DoSomething; 
{$region 'xmldoc'} 
///<summary></summary> 
///<author>skamradt</author> 
///<param name=''></param> 
///<returns></returns> 
///<exception cref=""></exception> 
///<since>2009-05-22</since> 
{$endregion} 
{------------------------------------------------------------------------------} 
begin 
    // code goes here. 
end;