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

[David Hendricks]

So it looks like we're pretty much all in agreement with 1-line and >=3
line comments. My only real concern is if "--ignore BLOCK_COMMENT_STYLE" in
the patch removes the check for the long comments, though I confess to
being ignorant of how checkpatch works.

To chip in my own $0.02 on the 2-line comment discussion: IMO they should
use the same form as 1-line comments so that we have exactly one form for
short comments one form for long comments.


On Fri, Aug 26, 2016 at 2:40 PM, Nico Huber <nico.h at gmx.de> wrote:

> On 26.08.2016 17:56, Vadim Bendebury wrote:
> > I actually tend to agree with Julius that it does not make sense to
> waste 4
> > lines for a two line comment.  So, ideally the tool should be enforcing
> the
> > verbose style for comments longer than say 2 lines.
>
> Well, I too prefer the concise style for shorter comments. But I
> wouldn't enforce a number of lines. Maybe just say it's allowed for
> single-paragraph comments?
>
> And thanks, Julius, for bringing up the readability. This is what we
> should focus on. Actually I think a verbose-style comment shouldn't be
> allowed between code lines. That's something for longer explanations
> like a function description.
>
> 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.
>
> I wouldn't go as far as changing current code, but enforcing a style
> (we can agree on) for new code might prevent future discussions.
>
> Nico
>
> --
> coreboot mailing list: coreboot at coreboot.org
> https://www.coreboot.org/mailman/listinfo/coreboot
>



-- 
David Hendricks (dhendrix)
Systems Software Engineer, Google Inc.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.coreboot.org/pipermail/coreboot/attachments/20160826/752e0801/attachment.html>