[coreboot] Proposal for new "Commenting" wiki text (was: [RFC] Deciding on style for multi-line comments)

[Nico Huber]

On 06.09.2016 00:04, Vadim Bendebury wrote:
> On Sun, Sep 4, 2016 at 7:42 AM, Nico Huber <nico.h at gmx.de> wrote:
> 
>> Hi folks,
>>
>> I think we kind of agreed that the wiki text about "Commenting" should
>> change. So here is my proposal, feel free to edit, add something or just
>> ack or complain about it.
>>
>>> == Commenting ==
>>>
>>> Comments are good, but there is also a danger of over-commenting. NEVER
>>> try to explain HOW your code works in a comment: it's much better to
>>> write the code so that the _working_ is obvious, and it's a waste of
>>> time to explain badly written code.
>>>
>>> Generally, you want your comments to tell WHAT your code does, not HOW.
>>> Also, try to avoid complex comments inside a function body: if the
>>> function is so complex that you need to separately comment parts of it,
>>> you should probably go back to chapter 6 for a while.  You can make
>>> small comments to note or warn about something particularly clever (or
>>> ugly), but try to avoid excess.  Instead, put the comments at the head
>>> of the function, telling people what it does, and possibly WHY it does
>>> it.
>>>
>>> coreboot style for comments is the C89 "/* ... */" style. You may also
>>> use C99-style "// ..." comments.
>>>
>>> The preferred style for concise multi-line comments that explain a
>>> single piece of code is:
>>>
>>>       /* This is the preferred style for
>>>          shorter multi-line comments that
>>>          avoids excessive blank lines. */
>>
> 
> why does the concise style have to be so different from the verbose style?
> Lines starting with '* ' are easier identifiable as comments.

Well, until now, there were only arguments against and none for the lea-
ding asterisk. In [1] Linus calls it "visually unbalanced".

And let me quote my argument:
> But I'm really with Linus when it comes to the leading, single asterisk.
> It looks totally weird, IMHO
> 
>   /* A small, concise comment
>      that doesn't fit a single line */
> 
> is easier for the eye than
> 
>   /* A small, concise comment
>    * that doesn't fit a single line */
> 
> where your eyes somehow stick on the asterisk first and then have to
> search for the real start of the line.

Nico

[1] https://lkml.org/lkml/2016/7/8/625

> 
> --vb
> 
> 
> 
> 
>>>
>>> Note that there shouldn't be leading asterisks on new lines in the
>>> concise style.
>>>
>>> The preferred style for long multi-line comments is:
>>>
>>>       /*
>>>        * This is the preferred style for multi-line
>>>        * comments in the coreboot source code.
>>>        *
>>>        * Description: A column of asterisks on the left side,
>>>        * with beginning and ending almost-blank lines.
>>>        */
>>>
>>> Some rules of thumb to decide which style to use:
>>> * If you are commenting a whole function (indentation level 0) or
>>>   something high level (indentation level 1), use the long style.
>>> * If you want to explain a single piece of code and your comment
>>>   doesn't span multiple paragraphs, use the concise style.
>>> * Otherwise you might want to ask yourself why what you're going to
>>>   explain doesn't deserve an own function.
>>>
>>> It's also important to comment data, whether they are basic types or
>>> derived types.  To this end, use just one data declaration per line (no
>>> commas for multiple data declarations).  This leaves you room for a
>>> small comment on each item, explaining its use.
>>>
>>> In case of doubt, the author of the code shall have the last word on
>>> comment styles. He should know best which style makes his code most
>>> readable.
>>
>> Nico
>>
>