Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

In languages that distinguish between a "source" and "header" file (mainly C and C++), is it better to document functions in the header file:

(pilfered from CCAN)

/**
 * time_now - return the current time
 *
 * Example:
 *  printf("Now is %lu seconds since epoch\n", (long)time_now().tv_sec);
 */
struct timeval time_now(void);

or in the source file?

(pilfered from PostgreSQL)

/*
 * Convert a UTF-8 character to a Unicode code point.
 * This is a one-character version of pg_utf2wchar_with_len.
 *
 * No error checks here, c must point to a long-enough string.
 */
pg_wchar
utf8_to_unicode(const unsigned char *c)
{
...

Note that some things are defined in the header only, such as structs, macros, and static inline functions. I'm only talking about things that are declared in a header file and defined in a source file.

Here are some arguments I can think of. I am leaning toward documenting in the source file, so my "Pro-header" arguments may be somewhat weak.

Pro-header:

  • The user doesn't need the source code to see the documentation.
    • The source may be inconvenient, or even impossible, to acquire.
    • This keeps interface and implementation further apart.

Pro-source:

  • It makes the header a lot shorter, giving the reader a birds-eye view of the module as a whole.
  • It pairs the documentation of a function with its implementation, making it easier to see that a function does what it says it does.

When answering, please be wary of arguments based on what tools and "modern IDEs" can do. Examples:

  • Pro-header: Code folding can help make commented headers more navigable by hiding the comments.
  • Pro-source: cscope's Find this global definition feature takes you to the source file (where the definition is) rather than the header file (where the declaration is).

I'm not saying don't make such arguments, but bear in mind that not everyone is as comfortable with the tools you use as you are.

share|improve this question
    

6 Answers 6

up vote 27 down vote accepted

My view...

  • Document how to use the function in the header file, or more accurately close to the declaration.

  • Document how the function works (if it's not obvious from the code) in the source file, or more accurately, close to the definition.

For the birds-eye thing in the header, you don't necessarily need the documentation that close - you can document groups of declarations at once.

Broadly speaking, the caller should be interested in errors and exceptions (if only so they can be translated as they propogate through the layers of abstraction) so these should be documented close to the relevant declarations.

share|improve this answer
6  
+1 - ie document the interface in the header. The Gory details of the how and why in the source. –  quickly_now Jun 15 '11 at 12:30

If you're going to use a tool such as Doxygen (note in the first example, that really looks like a Doxygen comment because it starts with /**) then it doesn't really matter - Doxygen will look through your header and source files and find all the comments to generate the documentation.

However, I'd be more inclined to put the documentation comments in the headers, where the declarations are. Your clients are going to deal with the headers to interface with your software, the headers are what they will be including in their own source files and that's where they will be looking first to see what your API looks like.

If you look at most Linux libraries for example, your Linux package management system often has a package that contains only the binaries of the library (for "normal" users who have programs that need the library) and you have a "dev" package that contains the headers for the library. The source code is not normally supplied directly in a package. It would be really cumbersome if you would have to get the source code of a library somewhere to get the documentation of the API.

share|improve this answer
    
+1 - with a provise that even if you use Doxygen, that doesn't mean you're never going to read directly from the source. Doxygen annotations are even sometimes useful as standard patterns to grep for, and it's handy if the annotation you find is close to the code it describes. –  Steve314 Jun 15 '11 at 7:38
1  
@Steve314 ofcourse I didn't say that you'd never want to look at the source code of some library - but that wouldn't be the first place you'd look for what the API looks like and how to use it. –  Jesper Jun 15 '11 at 7:41
    
I would also advocate to keep everything related to the API in the header (or at least in either the header or the source), since it would avoid potential incoherence when updating the documentation in one place and not the other. –  jopasserat Dec 10 at 12:21

We solved this problem (about 25 years ago) by creating a bunch of #defines (e.g. public, private, etc., that resolved to <nothing>) that could be used in the source file and were scanned by an awk script (horrors!) to auto-generate the .h files. This mean that all of the comments lived in the source and were copied (when appropriate) into the generated .h file. I know that it's pretty Old School, but it vastly simplified this kind of inline documentation.

share|improve this answer

If the stakeholders of your source code (say, a small library) consists of "users" (fellow developers who will use your library's functionality without getting involved in its implementation) and "developers" (you and other developers who will implement the library), then put the "users' information" in the header and "implementation note" in the source.

With regard to the desire to not change the header files more than is absolutely necessary - I suppose if your library is not "in a crazy flux of changes", that the "interface" and the "functionarity" will not change much, and neither should the header comments change too frequently. On the other hand, source code comments will have to be kept synchronized ("fresh") with the source code.

share|improve this answer

Comments are not documentation. The documentation for a function might typically be 2K of text, possibly with diagrams - see for example the documentation for functions in the Windows SDK. Even if your comment-to-doc allows such a thing, you will be making the code that contains the comment unreadable. If you want to produce documentation, use a word-processor.

share|improve this answer

In my (rather limited and biased) opinion, I am pro-source code way of thinking. When I do bits and pieces in C++, I usually edit the header file once and then I never really go back to look at it.

When I place documentation in the source file, I am always seeing it when I'm editing or reading codes. I guess it's a thing of habit.

But that's just me...

share|improve this answer
1  
Does not work very well if all you have is a compiled library and the header file. In that case, more info in header is a good thing because its the only interface documentation you have. –  quickly_now Jun 15 '11 at 12:31

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.