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

[Simon Glass]

Hi Masahiro,

On 19 September 2014 23:34, Masahiro YAMADA <yamada.m at 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.

Of course the best location depends on what you are using the code
for. In your case you are working through the C code I presume,
figuring out how everything works.

I think more common is to read through the header files trying to
understand the API. How things actually work until the hood can be
useful at times, but if the API and docs are good then perhaps you
don't need to read much further. For example, I figured out how SPI
worked mostly by looking at spi.h, and the probe function. I didn't
read all the C code. I think that the C code is a big burden for
people who are coming into a subsystem and trying to understand it a
bit.

It's nice to have a keystroke to jump between the declaration and
implementation of a function.

Actually I think I have said a similar thing to Albert.

I also agree that we don't really need to decide - having comments at
all is a bonus in some areas of the code!

Regards,
Simon