<div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote">On Sun, Sep 4, 2016 at 7: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></blockquote><div><br></div><div>why does the concise style have to be so different from the verbose style?  Lines starting with '* ' are easier identifiable as comments.</div><div><br></div><div>--vb</div><div><br></div><div><br></div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
><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></div>