my style of commenting
I think everybody has a different style of commenting. Mine is as follows:
/* function-name: (arguments [a brief label for what they're supposed to be])- (result)
computes [tell what it does, not how it does it]
SIDE-EFFECTS: blah [of course, only if the function has a side-effect] */
... // usually I don't put any comments here at all! OTOH, my functions are rarely 10 lines
In addition, I always have a document somewhere that has a roadmap for how the program works. High-level, it says something like: "there are 3 major components: the parser, the type-checker, and the interpreter. Processing starts at the main function which invokes the parser with a file handle. The parser generates a parse-tree, possibly with errors. If there are errors, it additionally sets the global variable errs to the number of errors encountered ... blah blah blah ...
"The parser has an interface defined in parser.h. The type-checker has an interface defined in type-checker.h. The interpreter's interface is in interpreter.h. See those files for descriptions of how those modules work."
I find that style of commenting allows for comments that are very helpful but that don't simply copy the code: high level descriptions are very valuable because they let you quickly get a good understanding of how even a very large software package works, and function-level documentation is very good for letting future coders quickly read sections of code and understand what's happening. If you do those things and you keep your functions small, then inline comments are usually redundant -- your code ought to document itself through your choosing clear algorithms and good function and variable names. On occasion, you might need to explain why your algorithm works, but that's about it.