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

[Nico Huber]

On 04.09.2016 21: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'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. */
> 

Sounds good.

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

Yes, that's much better. I just included that paragraph as I remembered
something like "the author should know best" from the discussion.

Thank you,

Nico