How to properly comment [closed]

Question

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.

Answer 1

C files should contain the usual comments you write anywhere when you write code. What does it do and why. Usually at the end of each line unless there is a need for more extensive comments.

H files can either contain a brief minimum, explaining what a function takes as parameters and what it returns. Or alternatively it could contain a full documentation of how the function should be used. If the full documentation is not provided in the header file, you will have to write it separately. Note: a few lines of Doxygen crap just to generate some manner of useless "documentation" file does not count as complete documentation.

H files document what a function does and how it should be used, without mentioning implementation details. It is important is to realize that a h file should be the full, stand-alone interface for the corresponding c file (or library). All types and dependencies (includes) that the caller needs to be aware of should be present in the h file.

This includes any pre- and post-conditions: What needs to be executed prior to calling a function? What resources did the function use? Did it leave any handles/files/resources open that need to be cleaned up later? Did it alter some global state? Etc etc.

The corresponding c file(s) are not necessarily made available to the user, nor should the user need to read the c file in order to understand how the functions there should be used. Everything should be made obvious from the h file alone.