[coreboot] Proposal for new "Commenting" wiki text (was: [RFC] Deciding on style for multi-line comments)

[Vadim Bendebury]

On Sun, Sep 4, 2016 at 7:42 AM, Nico Huber <nico.h at gmx.de> 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. */
>

why does the concise style have to be so different from the verbose style?
Lines starting with '* ' are easier identifiable as comments.

--vb




> >
> > 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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.coreboot.org/pipermail/coreboot/attachments/20160905/d1851d8f/attachment.html>