[coreboot] [RFC] Deciding on style for multi-line comments
Nico Huber
nico.h at gmx.de
Fri Aug 26 23:40:17 CEST 2016
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
More information about the coreboot
mailing list