views:

175

answers:

6

I'm writing a whitepaper and realized that I am not sure what the official term is for the kind of internal documentation that we put as a comment block before a declaration of definition.

The same thing that eventually becomes JavaDoc member documentation.

It's not simply internal documentation, and I'm not sure "header documentation" would be a good term.

Note that I'm looking for a general term, not one specific to a particular language (e.g., Java/Perl)

A: 

It's often professionally referred to as a "requirements clause", or an "insurance clause".

BKimmel
+3  A: 

At my organization we call it a method or function doc-comment. Function-level documentation is probably the more widely used term.

Bill the Lizard
+2  A: 

I always call it method (or function) comment, to distinguish it from class or file comments.

Thomas Owens
A: 

I call it code comments, simple like that.

Kind Regards

marcospereira
+4  A: 

This is called a method specification or procedure specification. That is, it specifies the behaviour of the procedure rather than the implementation details. Some text books refer to it as the contract of the method but that may be a bit ambiguous.

Vincent Ramdhanie
A: 

I usually refer to it as "inline documentation." To me that's what it's about — the fact that your documentation is in your source code, so there's more of a chance the docs will stay in sync with the code.

(This is no guarantee, of course, but it does encourage programmers to eat their vegetables. It means the developer can change the documentation at the same time and in the same place the behavior changes, rather than after the fact and in another place.)

savetheclocktower