0

Suppose we have function (external only considered here) int foo(int a, char *b), normally there will be a header that goes with it documenting what the function does, what each parameter and return value does, etc. It'll probably be in doxygen format too. My habit is that such header should go into .h files because that's where the interface is defined and reader should have all the information in that place. But a lot of people keep such headers in C file where the actual implimentation goes. I've seen this in the Linux kernel code also. So was I wrong? Which would you prefer?

lang2
  • 11,433
  • 18
  • 83
  • 133
  • Do you mean where the documentation comment should go? If the documentation is not the source file itself, but pre-processed away by (say) doxygen, then the real documentation are the HTML/PDF files, so it doesn't matter if it is in the `.h` or `.c`. – jxh Aug 20 '13 at 02:10
  • 2
    I should add, the important thing is consistency, so that future developers can follow a predictable and accepted coding practice. – jxh Aug 20 '13 at 02:25
  • @jxh Yes the documentation comment. I'm only considering code browsing scenario. Using HTML/PDF obviously doesn't matter. – lang2 Aug 20 '13 at 02:25

3 Answers3

3

Although header files can be used in any which way, they are primarily a mechanism to enable external linkage.

You design an API that is meant for external consumption, and you put everything required to consume this API (constants, types, prototypes) in header file(s).

All the other stuff, that is a part of implementation, and doesn't need to be seen by external users, can go in the source files (if the usage is localized to one file), or private headers that can be shared between multiple files. The latter is another example of header files enabling external linkage, but for internal consumption.

Ziffusion
  • 8,779
  • 4
  • 29
  • 57
1

The answer to this question is largely "it depends":

Depends on what? Who's reading the documentation, and how they access it.

If you're developing a program, then having the documentation inline with the implementation is probably OK, because anybody who wants to know about your program can access the source code and read about it. Your target audience is probably developers working on the program itself, so having the documentation in the C file, along with the bulk of the code they're working on, is a suitable approach.

If you're developing a library, the target audience changes (or you might have two target audiences). You still have the developers, who could make use of more detailed documentation as it relates to private implementation detail. You also have the users of the library, who only care about the interface that they're working with; from a code-browsing point of view, they typically only have access to the headers.

Anthony
  • 12,177
  • 9
  • 69
  • 105
0

I put them in the .h file by preference when it's my choice, if I have a .h file. If I just have a .c file, I will document the functions when they are defined, simply because if I just have a .c file, I'm probably still coding, and I want to change the documentation if I change the code.

I feel that documentation and declarations go together in a separate file in a finished c project. Documentation in the code breaks up the code and can be redundant.

If I'm contributing somewhere, I'll follow the established convention.

lsiebert
  • 667
  • 1
  • 5
  • 16
  • "*Documentation in the code breaks up the code ...*" could you please elaborate on this. I feel source ocde documentation is essential. Perhaps your are referring to a different kind of documentation? – alk Aug 20 '13 at 06:19
  • sure. There are two types of documentation I mainly consider: Documentation that explains the code, and documentation that explains how to use the code. The former should, of course, be in the code. But if you are just saying that void string_reverse(char * string, size_t string_len) takes a string and a string length and reverses the string in place, that isn't describing how the code works, that's how you would use it. That should be in the header. – lsiebert Aug 28 '13 at 03:14