Question

I work with a team called the Solar Jackets at Georgia Tech, and we have been having a “commenting crisis”. We have many members that graduate, and leave behind comment-less code. I am looking to implement a commenting standard, so that this does not happen, and I need some suggestions to make sure I have all of my bases covered.

What I want is the following functionality:

• A consolidated place, where you can view every functions description,
  including includes, arguments, return types, and a general
  description of the code. (generated from the comments in the code)

• In the code itself, a line by line (or close to) description.

Is there any suggestions of what I may have left out? Are there are any programs that can automatically generate the code compilation? How could I make this easier on the programmers?

Answer 1

what you describe reminds me of Doxygen. It has a format for commenting all entities in the code including functions, parameters, variables,…
It can be used to enforce everything is been documented by checking the warnings generated by Doxygen. It generates the complete document off of the source code in differents formats like HTML, Latex, PDF,…

Many IDEs know Doxygen tags and can be integrated with Doxygen to help developer on commenting the code.

here is an example of Doxygen comment:

/**
 * @brief This function does blah blah.
 * @param test blah blah parameter.
 * @return 0 if blah blah passed.
 */
uint32_t TestFunction( uint32_t test )
{
    return 0;
}