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

[Vadim Bendebury]

I say let's stick with the Linux kernel style, this makes it easier to use
the tools.

And being a much bigger and much more mature codebase, kernel is not a bad
example to follow in general.

--vb

On Wed, Aug 24, 2016 at 12:08 AM, Paul Menzel via coreboot <
coreboot at coreboot.org> wrote:

> 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
> --
> coreboot mailing list: coreboot at coreboot.org
> https://www.coreboot.org/mailman/listinfo/coreboot
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.coreboot.org/pipermail/coreboot/attachments/20160824/89e43ec4/attachment.html>