Where to document functions in C or C++? [closed]

Answer 1

It's simple really when you think about it.

The API docs absolutely must go in the header file. It's the header file that defines the external interface, so that's where the API docs go.

As a rule, implementation details should be hidden from API users. This includes documentation of implementation (except where it might affect the use e.g. time complexity etc). Thus implementation documentation should go in the implementation file.

Never ever duplicate documentation in multiple places. It will be unmaintainable and will be out of sync almost as soon as somebody has to change it.

Answer 2

I like to follow the Google C++ Style Guide.

Which says:

Function Declarations

• Every function declaration should have comments immediately preceding it that describe what the function does and how to use it. These comments should be descriptive ("Opens the file") rather than imperative ("Open the file"); the comment describes the function, it does not tell the function what to do. In general, these comments do not describe how the function performs its task. Instead, that should be left to comments in the function definition.

Function Definitions

• Each function definition should have a comment describing what the function does and anything tricky about how it does its job. For example, in the definition comment you might describe any coding tricks you use, give an overview of the steps you go through, or explain why you chose to implement the function in the way you did rather than using a viable alternative. For instance, you might mention why it must acquire a lock for the first half of the function but why it is not needed for the second half.

  Note you should not just repeat the comments given with the function declaration, in the .h file or wherever. It's okay to recapitulate briefly what the function does, but the focus of the comments should be on how it does it.

Answer 3

You should use a tool like doxygen, so the documentation is generated by specially crafted comments in your source code.

Answer 4

I wrote a simple script that takes as input a template header-file with no function declarations and a source-code file with commented functions. The script extracts the commentary before a function definition from the source code file and writes it and the associated function declaration into an output header-file. This ensures that 1) there's only one place where function commentary needs to be written; and 2) the documentation in the header-file and the source code file always remain in sync. Commentary on the implementation of a function is put into the body of the function and is not extracted.

Answer 5

The comments in the header vs. the implementation file should reflect the difference in how the two are used.

If you're going to create interface documentation (e.g., to be extracted with Doxygen, on the same general order as JavaDocs) that clearly belongs in the header. Even if you're not going to extract the comments to produce separate documentation, the same general idea applies -- comments that explain the interface/how to use the code, belong primarily or exclusively in the header.

Comments in the implementation should generally relate to the implementation. Contrary to frequent practice, rather than attempting to explain how things work, most should explain why particular decisions were made. This is especially true when you make decisions that make sense, but it might not be obvious that they do (e.g., noting that you did not use a Quicksort, because you need a stable sort).

Answer 6

• Put the information that people using the functions need to know in the header.

• Put the information that maintainers of the functions need to know in the source code.