On 05.09.2016 18:34, tmiket wrote: > 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.
Welcome to coreboot, then :) > > 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? I wouldn't call it "hidden". As with most wikis, there is just no com- prehensive TOC. > > It appears more detailed than the corresponding Coding Style in the > Development Guidelines page. Actually, that page links to Coding_Style in section 2.5. But maybe we should link it on the Welcome page, too. Regards, Nico > > 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 <[email protected]> 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 -- coreboot mailing list: [email protected] https://www.coreboot.org/mailman/listinfo/coreboot
