[C++] Function headers in header or source file?
^ Pretty much what the subject states.
I've had a few conflicting opinions whether function headers should be in the header or source files.
The argument for source is that adding them to the header file will make the header file large and far harder to read than without.
The argument for header is that the header file will be the first place someone will look when wanting to use an instance of a class and see what functions a class may have and a description of each function would make most sense there.
What's your opinion?
Jonathan
What do you mean by "function headers"? Do you mean comments explaining what the functions do?
Yeah.
Explaining what conditions parameters require before being pasted to the function, what the outcome of the function will be, describing the meaning of each parameter and return value and a general description of how the function works.
Explaining what conditions parameters require before being pasted to the function, what the outcome of the function will be, describing the meaning of each parameter and return value and a general description of how the function works.
[opinion]
Put them in the header file. Always code like someone else will be using your code. As such make it as easy as possible to use. This means that as a user of your code I don't want to have to wade through the implementations of your functions to read the descriptions.
Think of it like this: the header file is for clients of the class, the cpp is for the developer of the class. just because you happen to be both, doesn't mean you should rely on your own understanding in 5 or 6 months! [grin]
[/opinion]
Put them in the header file. Always code like someone else will be using your code. As such make it as easy as possible to use. This means that as a user of your code I don't want to have to wade through the implementations of your functions to read the descriptions.
Think of it like this: the header file is for clients of the class, the cpp is for the developer of the class. just because you happen to be both, doesn't mean you should rely on your own understanding in 5 or 6 months! [grin]
[/opinion]
Use an automated documentation generator, like Natural Docs or Doxygen, for your project. Put the comments where the generator says they should go.
This topic is closed to new replies.
Advertisement
Popular Topics
Advertisement