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