On 06.09.2016 00:04, Vadim Bendebury wrote:
On Sun, Sep 4, 2016 at 7:42 AM, Nico Huber
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
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. */
why does the concise style have to be so different from the verbose style?
Lines starting with '* ' are easier identifiable as comments.
Well, until now, there were only arguments against and none for the lea-
ding asterisk. In  Linus calls it "visually unbalanced".
And let me quote my argument:
But I'm really with Linus when it comes to the
leading, single asterisk.
It looks totally weird, IMHO
/* A small, concise comment
that doesn't fit a single line */
is easier for the eye than
/* A small, concise comment
* that doesn't fit a single line */
where your eyes somehow stick on the asterisk first and then have to
search for the real start of the line.
Note that there shouldn't be leading asterisks on new lines in the
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