[coreboot] Proposal for new "Commenting" wiki text

[Paul Menzel]

Dear Nico,


Thank you for taking this up again.


Am Samstag, den 28.01.2017, 15:00 +0100 schrieb Nico Huber:
> 
> sorry to revive this old, stale topic. I got stalled by a request to
> ensure the comment style with a script. Now, that I had a look at
> checkpatch.pl, I don't think this could be done easily without risking
> many false positives.
> 
> So I'm again asking to commit my proposal below. I've incorporated the
> comments from Martin.

Just to be clear, also for the proposal below, the style can’t be
checked, right?

> Even if it's not going to be my preferred style, I would really appre-
> ciate it if we could agree on one style.
> 
> Nico
> 
> > == 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.

Could we change that, C89 style comments are preferred, and add a note about consistency?

> … You may also use C99 style "// …" comments, if it’s beneficial.
> Also, the commenting should be consistent in one file.

Or is that wishful thinking, and both style will always be mixed?

> > The preferred style for concise multi-line comments that explain a
> > single piece of code is:

Please, emphasize *concise*, or elaborate right away with *i. e., one
paragraph*

> > 
> >  	/* This is the preferred style for
> >  	   two or three 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:

Please emphasize *long*.

> >  	/*
> >  	 * 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.
> > 
> > If the author has reasonable arguments for breaking the recommended
> > style guide to improve readability, others should be respectful of those
> > differences.

Nico, thank you again.


Thanks,

Paul
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 195 bytes
Desc: This is a digitally signed message part
URL: <http://www.coreboot.org/pipermail/coreboot/attachments/20170129/c9a44dd0/attachment.asc>