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 -- coreboot mailing list: [email protected] https://www.coreboot.org/mailman/listinfo/coreboot
