[coreboot] Proposal for new "Commenting" wiki text (was: [RFC] Deciding on style for multi-line comments)
nico.h at gmx.de
Wed Sep 7 23:42:18 CEST 2016
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
> 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
> 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
> 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
> 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
> 4) I think this would be the only "the author has the final say" policy -
> 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
> 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.
More information about the coreboot