<div dir="ltr"><div>Hey Nico,</div>Thanks for writing that up and not just letting this drop with no<div>resolution and action.<br><div><br></div><div>To anyone just coming in on the discussion, here's what we're talking about</div><div>changing:</div><div><a href="https://www.coreboot.org/Coding_Style#Commenting">https://www.coreboot.org/Coding_Style#Commenting</a><br></div><div><br></div><div><br></div><div>I'd suggest just a couple of changes to your update:<div><br></div><div>Let's define what a "short" comment is to avoid future arguments that 10</div><div>lines is short:</div><div><span style="font-size:12.8px">> /* This is the preferred style for</span><br style="font-size:12.8px"><span style="font-size:12.8px">> two or three line comments that</span><br style="font-size:12.8px"><span style="font-size:12.8px">> avoids excessive blank lines. */</span><br style="font-size:12.8px"></div><div><br></div><div><br></div><div><span style="font-size:12.8px">And I'm not certain of this paragraph, and I'd recommend removing or </span></div><div><span style="font-size:12.8px">changing it a bit.</span></div><div><span style="font-size:12.8px"><br></span></div><div><span style="font-size:12.8px">> In case of doubt, the author of the code shall have the last word on</span><br style="font-size:12.8px"><span style="font-size:12.8px">> comment styles. He should know best which style makes his code most</span><br style="font-size:12.8px"><span style="font-size:12.8px">> readable.</span><span style="font-size:12.8px"><br></span></div><div><span style="font-size:12.8px"><br></span></div><div><span style="font-size:12.8px">1) I think that Stefan as the project leader should have the decision about</span></div><div><span style="font-size:12.8px"> </span><span style="font-size:12.8px">anything that is </span><span style="font-size:12.8px">controversial enough to need a last word.</span></div><div><span style="font-size:12.8px">2) What if the author is female? :) Maybe use 'they' as the pronoun if this</span><br></div><div><span style="font-size:12.8px">paragraph </span><span style="font-size:12.8px">is left in. Not a big deal, but I'd like to be inclusive.</span></div><div><div><span style="font-size:12.8px">3) I think this might be just asking for arguments. I'm not talking about anyone</span></div><div><span style="font-size:12.8px">specific, just thinking of discussions in the past.</span></div><div><span style="font-size:12.8px"> -- "As the author I LIKE ascii art in </span><span style="font-size:12.8px">my comments and I get the final say."</span></div></div><div><span style="font-size:12.8px"> -- We're going to get lawyer arguments: "It says above that the c99 style</span></div><div><span style="font-size:12.8px"> is valid - why can't we just prefix the </span><span style="font-size:12.8px">whole 16 line </span><span style="font-size:12.8px">block with '//'"?</span></div><div><span style="font-size:12.8px"> -- "I know it says not to say 'increment i', but as the author, I think it's</span></div><div><span style="font-size:12.8px"> helpful."</span></div><div><span style="font-size:12.8px">4) I think this would be the only "the author has the final say" policy - what</span></div><div><span style="font-size:12.8px">happens when someone rewrites the comment in a following patch? Who</span></div><div><span style="font-size:12.8px">is the author?</span></div><div><span style="font-size:12.8px"><br></span></div><div><span style="font-size:12.8px">Maybe we could change it from "has the last word" to something saying like:</span></div><div><span style="font-size:12.8px"><br></span></div><div><span style="font-size:12.8px">> If the author has reasonable arguments for breaking the recommended</span></div><div><span style="font-size:12.8px">> style guide to improve readability, others should be respectful of those</span></div><div><span style="font-size:12.8px">> differences.</span></div><div><span style="font-size:12.8px"><br></span></div><div><span style="font-size:12.8px">I think this preserves the intent without some of the issues.</span></div><div><span style="font-size:12.8px"><br></span></div><div><span style="font-size:12.8px">Martin</span></div><div><br></div><div><span style="font-size:12.8px"><br></span></div><div><span style="font-size:12.8px"><br></span></div><div><span style="font-size:12.8px"><br></span></div><div><span style="font-size:12.8px"><br></span></div><div><span style="font-size:12.8px"><br></span></div></div></div></div><div class="gmail_extra"><br><div class="gmail_quote">On Sun, Sep 4, 2016 at 8:42 AM, Nico Huber <span dir="ltr"><<a href="mailto:nico.h@gmx.de" target="_blank">nico.h@gmx.de</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">Hi folks,<br>
<br>
I think we kind of agreed that the wiki text about "Commenting" should<br>
change. So here is my proposal, feel free to edit, add something or just<br>
ack or complain about it.<br>
<br>
> == Commenting ==<br>
><br>
> Comments are good, but there is also a danger of over-commenting. NEVER<br>
> try to explain HOW your code works in a comment: it's much better to<br>
> write the code so that the _working_ is obvious, and it's a waste of<br>
> time to explain badly written code.<br>
><br>
> Generally, you want your comments to tell WHAT your code does, not HOW.<br>
> Also, try to avoid complex comments inside a function body: if the<br>
> function is so complex that you need to separately comment parts of it,<br>
> you should probably go back to chapter 6 for a while. You can make<br>
> small comments to note or warn about something particularly clever (or<br>
> ugly), but try to avoid excess. Instead, put the comments at the head<br>
> of the function, telling people what it does, and possibly WHY it does<br>
> it.<br>
><br>
> coreboot style for comments is the C89 "/* ... */" style. You may also<br>
> use C99-style "// ..." comments.<br>
><br>
> The preferred style for concise multi-line comments that explain a<br>
> single piece of code is:<br>
><br>
> /* This is the preferred style for<br>
> shorter multi-line comments that<br>
> avoids excessive blank lines. */<br>
><br>
> Note that there shouldn't be leading asterisks on new lines in the<br>
> concise style.<br>
><br>
> The preferred style for long multi-line comments is:<br>
><br>
> /*<br>
> * This is the preferred style for multi-line<br>
> * comments in the coreboot source code.<br>
> *<br>
> * Description: A column of asterisks on the left side,<br>
> * with beginning and ending almost-blank lines.<br>
> */<br>
><br>
> Some rules of thumb to decide which style to use:<br>
> * If you are commenting a whole function (indentation level 0) or<br>
> something high level (indentation level 1), use the long style.<br>
> * If you want to explain a single piece of code and your comment<br>
> doesn't span multiple paragraphs, use the concise style.<br>
> * Otherwise you might want to ask yourself why what you're going to<br>
> explain doesn't deserve an own function.<br>
><br>
> It's also important to comment data, whether they are basic types or<br>
> derived types. To this end, use just one data declaration per line (no<br>
> commas for multiple data declarations). This leaves you room for a<br>
> small comment on each item, explaining its use.<br>
><br>
> In case of doubt, the author of the code shall have the last word on<br>
> comment styles. He should know best which style makes his code most<br>
> readable.<br>
<span class="HOEnZb"><font color="#888888"><br>
Nico<br>
</font></span></blockquote></div><br></div>