I usually comment behind the function declaration in my header files, too.

// This function does absolutely nothing!
void complex_function(std::string heystring); // I dunno what this does
void new_function(); // This function does absolutely nothing!

If i remember it, I copy the comment above each function inside the implementation file.

// This function does absolutely nothing!
void new_function()
{
}

When i do multiline comments, i have this weird idea to keep them aesthetically pleasing:

/*
* This is a lovely multiline comment (Monospaced beauty!)
* ----------------------------------------------------------
* and this is a brief description of a module,
* placed in a header file.
* # Todo:
* + Add random stuff.
* * Clean previous stuff.
* - Remove obsolete functions.
*/

- I put them in the top of my header files. They may take up around 25 lines and contain a title, a short description and
major features of the module, -as well as a crappy todo-list which i never update.

I rarely use multiline comments, unless i remove something temporarily, or if i need to explain an advanced function in implementation file.

Basically i only document really advanced algorithms, or hacks, or stuff that could otherwise be difficult to understand later.

... That's what I do.... :-/

I do this quite frequently. Once something is working it is much easier to see better ways for the code work. When implementing new things I try pretty hard to keep it clean but it is easy to do some quick hacks to get it working.

This extra time spent perfecting working code can save a lot of time in the future when you are extending the code.

Maybe you could benefit from looking at an automatic documentation generation tool, for example Doxygen. Even if you don't generate the documentation, it can help you create a good and consistent style for your comments and it forces you (well, sort of) to consistently document what you are doing, making it easier to find the right class or function later.

Personally, I find it easiest to grog code if it is split up into small logical units of functionality. Therefore I have many rather small files, most of them only with a single class with a single purpose. That way I can easily find that if I need functionality X then I need class X located in X.h and X.cpp. Large files with code for many different purposes are detrimental to understanding code and to code reuse, in my view.

Yes, I do both every time I touch the code.


When I start, I add comments to everything that I didn't instantly understand, or rename it so it doesn't require the comments. This will (hopefully) help the next person who comes through.

Then I remove code that is no longer relevant, and merge code that can be merged. Test and verify, then submit to version control.

Then I make my changes. I add comments to anything that I think might be confusing. Then I test, verify, and submit.

Then I clean up again, removing and merging whatever I can. Test and verify. Submit the code to version control, and be done.



If you don't take time to clean up the code EVERY TIME you use it, the code will quickly become a cluttered mess. Garbage will accumulate. Program performance will suffer, and programmer productivity will suffer. Nobody will be happy. Then people will want to throw the whole thing out and start over.

I comment directly in the source to anything that requires explanation and cannot be given a self-explanatory name. External documentation is rarely viewed and quickly obsolete. Put comments where they improve understanding, and remove them when they are no longer accurate.

Doing the little tasks before and after is necessary every time you modify code. Think of it as checking the equipment before use (e.g. oiling and dusting as necessary), making your change, and then cleaning up the dust and debris after the task is done.