Is it better to document functions in the header file or the source file?

Question

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.

Answer 1

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.

Answer 2

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.

Answer 3

Assuming this is code within a larger project (where developers will be moving between source and headers often), and providing this isn't a library/middle-ware, where others may not have access to the source, I've found this works best...

• Headers:
  Terse 1-2 line comments, only if they're needed.
  Sometimes comments above a group of related functions is helpful too.
• Source:
  Documentation on API directly above the function (plain-text or doxygen if you prefer).
• Keep implementation details, only relevant to a developer modifying the code in the body of the function.

The main reason for this is to keep the comments close to the code, I've noticed docs in headers tend to get out of sync with changes to the code more often (of course they shouldn't, but they did in our project at least). Also developers may add documentation at the top of functions when they make some change, even when there are docs in the header, causing double-ups or useful info only to be in one of the doc-strings.

Of course you can pick a convention and ensure all devs follow, I just found the convention above the most natural-fit and causes least trouble to maintain.

---

Last of all, for large projects - there is an inclination not to make small corrections in a header when you know its going to cause potentially 100's or 1000's of files to re-compile when others update version control - slowing down bisecting errors too.

Answer 4

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.

Answer 5

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.

Answer 6

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...

Answer 7

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.

Answer 8

The whole point of using doxygen is that you generate documentation and make it accessible somewhere else. Now all that documentation in the headers is just garbage which makes it more difficult to quickly spot the required funciton declaration, and maybe its overloads. One liner comment is maximum which should go there, but even that is bad practice. Cause if you change documentation in the source you recompile that source and relink. But if you put docs in the header you really do not want to change a slightest thing in there, cause it is going to trigger significant part of project rebuild.