Where to put documenting comments?

Question

Very short question: when documenting delphi code (for the purpose of enabling an external tool to generate an HTML documentation (Doc-o-matic in the concrete example)), do you put the documenting comments in the interface or in the implementation section?

What I like about the second approach is that the interface part a class stays clean and compact and that the documenting comments work as separators between functions in the implementation section.

On the other hande, Doc-o-matic seems to have problems from time to time when I put the documenting comments in the implementation part.

What do you prefer?

Answer 1

I prefer to document the code in implementation part which gives much visibility and ease to understand.

Answer 2

I put "Summary" comments into the interface, and the full description, parameters etc. into the implementation part. That way you can look at an Unit's/Class' interface and you see immediately what it does - without pollution...

Answer 3

It seems to me that it would be best to put the documentation next to the implementation. The implementation is where you're most likely to make changes to the code, and when you change the code, you'll want to review the documentation to ensure it's still accurate, so you may as well have the two nearby.

Olaf mentions including a description at the interface as well, and you ask how the documentation-generator chooses which comments to use. An easy solution is to simply not use the documentation generator's special comment format in the interface. It should ignore those comments as being ordinary non-documentation comments, and so the implementation's comments will be the only ones the generator uses. Or you could put a short description at the interface and a long description in the implementation, and the generator can use whichever one is most appropriate for the context (e.g., a list of all methods with one-line descriptions versus in-depth coverage of a single method).

SrbShell suggests putting the documentation in the interface, and it's certainly convenient to have everything nearby, when not using a documentation generator. But that becomes much less important when you have a program that collects documentation from throughout your code and puts it all together. In that case, the expectation is that you'll be using the generated documentation, too. When you have prepared documentation, refer to that instead of having to find the documentation in the code. The IDE can even be configured to display descriptions in a pop-up window, so you don't have to go look at it in a separate place most of the time.

I've been talking about what I see as the "ideal" mode. If your particular tool makes that strategy no-so-ideal anymore, then adapt it to fit the tool, or find a different tool.

Answer 4

I add a one-line summary comment to the interface section, and write the full-detailed comments in the implementation section.

BTW, I use Doc-O-Matic, and it works fine with comments in the implementation section. What are the problems you are facing when you write the comments in the implementation section?

Answer 5

I prefer to place my documentation in the interface BEFORE the object to explain any design issues, link to design documentation, or other things that the user of the object class would need to know. For methods, I document them separately and individually in the implementation section, immediately after the declaration, but before the begin. The header of every unit can contain an release notes/history section right after the unit name.

Typically, my method comment block looks like the following (via templates):

{==============================================================================}
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;