[RFC] Deciding on style for multi-line comments - coreboot

24 Aug 2016


      Dear coreboot folks,
The coding style currently demands the following style of multi-line
comments [1].
...
The preferred style for long (multi-line) comments is:
/*
     * This is the preferred style for multi-line
     * comments in the Linux kernel source code.
     * Please use it consistently.
     *
     * Description:  A column of asterisks on the left side,
     * with beginning and ending almost-blank lines.
     */
This is straight from the Linux Kernel coding style [2].
Certain parts of the code do not follow this style, so the question is
how to deal with this. There has been some discussion on Gerrit about
that [3]. But the list is the forum for such discussions, so I am
bringing it up here.
Julius’ last comment:
...
No offense, but that part of the Wiki literally reads:
...
For files in net/ and drivers/net/ the preferred style for long
(multi-line) comments is a little different.
...so I'm not really sure why we should take something that has
obviously been carelessly bulk-copy&pasted into there from Linux
kernel sources eons ago as more authoritative than living development
practice of the last few years.
The coreboot wiki is, sorry I have to say it, for the most part
pretty awful and outdated. It would probably be a good thing to fix
if somebody has the time for it, but until then I don't think we
should put too much stake into it (at least in the stuff that hasn't
been updated and maintained recently).
I think that the extra blank lines in multi-line comments make them
stand out better, which I prefer over having more lines on the screen.
Also staying close to the Linux Kernel coding style makes it easier to
use their tools, and not having to adapt them, and people only have to
remember one style.
But in the end it’s a matter of taste.
So what should be done? Adapt the coreboot coding syle, or gradually
change the style in the existing code, but require the style in new
commits?
Thanks,
Paul
[1] https://www.coreboot.org/Coding_Style#Commenting
[2] https://www.kernel.org/doc/Documentation/CodingStyle
[3] https://review.coreboot.org/16060