[U-Boot] [U-Boot, 2/3] image: move all function comments to header file

[Albert ARIBAUD <albert.u.boot@aribaud.net>]

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,
-- 
Albert.