This is a very simple question which I am surprised I haven't found anywhere else on SO. I was wondering which comments should or shall not be in header/source files and even, because some languages don't really use the header/source system, what is the proper way to comment.
So far I have been doing it like that :
main.c or main.cpp
int main()
{
// Comments to describe what happens in main
}
foo.h
// Comments for documentation and which gives information about the function itself
/**
* \fn void aFunction(void)
* \brief This function is a function
*/
void aFunction(void);
foo.c or foo.cpp
void aFunction(void)
{
// Comments to describe and explain what happens within this function
}
- Not much comments in main, just describing basically what functions are called and why
- In header, only comments to describe the function itself; parameters, brief, return etc.
- In source, only comments to describe what's happening within the function; loops, condition, etc.
That is what I know for sure. Are there more comments needed in either main, source or header ? Should I add the comments I usually only put in the header in the source too, like that :
foo.c or foo.cpp
/**
* \fn void aFunction(void)
* \brief This function is a function
*/
void aFunction(void)
{
// Comments to describe and explain what happens within this function
}
I know this may sound subjective, but it is an obvious fact that some devs are better at commenting than others, and thus that there are good and bad ways to comment.