Menu
I have a C program with multiple files, so I have, for example, stuff.c which implements a few functions, and stuff.h with the function prototypes.
How should I go about documenting the functions in comments?
Should I have all the docs in the header file, all the docs in the .c file, or duplicate the docs for both? I like the latter approach, but then I run into problems where I'll update the docs on one of them and not the other (usually the one where I make the first modification, i.e. if I modify the header file first, then its comments will reflect that, but if I update the implementation, only those comments will change).
This question and its answers also apply to C++ code — see also Where should I put documentation comments?
208
Function Declarations Function declaration is required when you define a function in one source file and you call that function in another file. In such case, you should declare the function at the top of the file calling the function.
C can differ quite much from compiler to compiler! @Auron: the specification is the only official documentation; however there are numerous non-official documentations that are much more accessible (both financially and linguistically).
As we all know that files with . h extension are called header files in C. These header files generally contain function declarations which we can be used in our main C program, like for e.g. there is need to include stdio. h in our C program to use function printf() in the program.
The execution of a C program begins from the main() function. And, the compiler starts executing the codes inside functionName() . The control of the program jumps back to the main() function once code inside the function definition is executed. Note, function names are identifiers and should be unique.
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.
112
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.
42
You should use a tool like doxygen, so the documentation is generated by specially crafted comments in your source code.
11
I've gone back and forth on this and eventually I settled on documentation in header files. For the vast majority of APIs in C/C++ you have access to the original header file and hence all of the comments that lie within [1]. Putting comments here maximizes the chance developers will see them.
I avoid duplication of comments between header and source files though (it just feels like a waste). It's really annoying when using Vim but most IDEs will pick up the header file comments and put them into things like intellisense or parameter help.
[1] Exceptions to this rule include generated header files from certain COM libraries.
9
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With
