Hi Masahiro,
On Sat, 20 Sep 2014 14:34:29 +0900, Masahiro YAMADA yamada.m@jp.panasonic.com wrote:
Hi.
I vote for comments near the implementation.
I have been digging into the driver model code recently, but I have to admit it is unreadable because most of comments are placed in its header files. (and I am planning to send a patch to move comments to C sources.)
I really want to know "what does this function do?" and "How is it used?" things before I start to read the detailed implementation.
If they are written separately, I need to open two windows of my editor, one for reading the comments in a header file, the other for reading the implementation in a C source. I am really unhappy about that.
I guess people often use tag jump utilities. (I like GNU Global, someone may use ctags/etags, cscope, etc. I don't know..)
Such utilities allow us to jump over to the implementation place. If comments are not there, we have to look for comments by hand.
I think we should keep in our mind this: source files are much more read than written. I believe we put the readers' benefits at the top priority.
The way I comment my own code (i.e., when not trying to adhere to coding rules/guidelines, or to the custom in existing code) is that I put comments in both places, declaration and definition, for two different purposes.
I put a block comment before the declaration to tell readers how to *use* the function -- what the arguments mean, what the result shall be, what particular conditions should be met on call, etc.
That's for people who *use* my code.
I put a block comment before the definition to tell readers how the function does its job, similar to a detailed design description but without the algorithm, because I consider the source code to *be* the detailed design algorithm.
That's for people who need to *change* my code.
(Then I put comments in the body code either to break it into identified steps, or to indicate things that do not derive from the design, e.g. compiler or linker bug workarounds, etc. but that's a bit beyond the point.)
As I said, that's /my/ way of writing /my/ code, my .02 EUR given just to point out that we don't necessarily have to decide to put comments in header *xor* body.
Amicalement,