I like to follow the Google C++ Style Guide.
Which says:
Function Declarations
- Every function declaration should
have comments immediately preceding
it that describe what the function
does and how to use it. These
comments should be descriptive
("Opens the file") rather than
imperative ("Open the file"); the
comment describes the function, it
does not tell the function what to
do. In general, these comments do not
describe how the function performs
its task. Instead, that should be
left to comments in the function
definition.
Function Definitions
Each function definition should have
a comment describing what the
function does and anything tricky
about how it does its job. For
example, in the definition comment
you might describe any coding tricks
you use, give an overview of the
steps you go through, or explain why
you chose to implement the function
in the way you did rather than using
a viable alternative. For instance,
you might mention why it must acquire
a lock for the first half of the
function but why it is not needed for
the second half.
Note you should not just repeat the
comments given with the function
declaration, in the .h file or
wherever. It's okay to recapitulate
briefly what the function does, but
the focus of the comments should be
on how it does it.
