[coreboot] Proposal for new "Commenting" wiki text

[Nico Huber]

On 05.09.2016 18:34, tmiket wrote:
> On 2016-09-04 12:36, Martin Roth wrote:
>> Hey Nico,Thanks for writing that up and not just letting this drop
>> with no
>> resolution and action.
>>
>> To anyone just coming in on the discussion, here's what we're talking
>> about
>> changing:
>> https://www.coreboot.org/Coding_Style#Commenting
> 
> I am new to this discussion and to coreboot.

Welcome to coreboot, then :)

> 
> This appears to be a "hidden" page in that the TOC on top left doesn't have
> a link called Coding Style.  Is this a new work in progress page?

I wouldn't call it "hidden". As with most wikis, there is just no com-
prehensive TOC.

>
> It appears more detailed than the corresponding Coding Style in the
> Development Guidelines page.

Actually, that page links to Coding_Style in section 2.5. But maybe we
should link it on the Welcome page, too.

Regards,
Nico

> 
> I'm asking because I start a new job that uses coreboot and I'm working
> my way through the online documentation.
> Cheers,
> T.mike
> 
>>
>> I'd suggest just a couple of changes to your update:
>>
>> Let's define what a "short" comment is to avoid future arguments that
>> 10
>> lines is short:
>>>       /* This is the preferred style for
>>>          two or three line comments that
>>>          avoids excessive blank lines. */
>>
>> And I'm not certain of this paragraph, and I'd recommend removing or
>> changing it a bit.
>>
>>> 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.
>>
>> 1) I think that Stefan as the project leader should have the decision
>> about
>>  anything that is controversial enough to need a last word.
>> 2) What if the author is female?  :)  Maybe use 'they' as the pronoun
>> if this
>>
>> paragraph is left in.  Not a big deal, but I'd like to be inclusive.
>>
>> 3) I think this might be just asking for arguments.  I'm not talking
>> about anyone
>> specific, just thinking of discussions in the past.
>>  -- "As the author I LIKE ascii art in my comments and I get the final
>> say."
>>  -- We're going to get lawyer arguments: "It says above that the c99
>> style
>>     is valid - why can't we just prefix the whole 16 line block with
>> '//'"?
>>  -- "I know it says not to say 'increment i', but as the author, I
>> think it's
>>      helpful."
>> 4) I think this would be the only "the author has the final say"
>> policy - what
>> happens when someone rewrites the comment in a following patch?  Who
>> is the author?
>>
>> Maybe we could change it from "has the last word" to something saying
>> like:
>>
>>> If the author has reasonable arguments for breaking the recommended
>>> style guide to improve readability, others should be respectful of
>> those
>>> differences.
>>
>> I think this preserves the intent without some of the issues.
>>
>> Martin
>>
>> On Sun, Sep 4, 2016 at 8: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. */
>>>>
>>>> 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