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

Julius Werner jwerner at chromium.org
Sat Aug 27 00:54:27 CEST 2016


>> 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.

FWIW I don't care about the difference between the two, I'd be happy
to switch to the former form if we decide that's what we want to do. I
only care about having full extra lines in there.

We've currently already merged --ignore=BLOCK_COMMENT_STYLE, so all of
these forms get accepted by Gerrit right now. I don't think a tool
that automatically reformats comments would work that well (that would
probably end up causing other unintended side effects), and I don't
think we should set a hard line limit to decide between comments
either. (For example, in a header file where you're describing the API
for every function prototype you'd probably want all of those to use
the same style, even if some of them are longer and some shorter than
the hardcoded limit.)

I think we should decide on the two styles of comments we want to
allow, and then we can either submit a patch to checkpatch (I'd hope
they'd accept it if it adds a configurable switch, such as
--comment-styles=blank_line_top_bottom,short_balanced_stars) or
enforce it through a separate script in util/lint/. And update the
Wiki page, of course.



More information about the coreboot mailing list