[coreboot] Proposal for new "Commenting" wiki text

[tmiket]

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.

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?

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

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