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

[Julius Werner]

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

-- 
coreboot mailing list: coreboot@coreboot.org
https://www.coreboot.org/mailman/listinfo/coreboot

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

[David Hendricks via coreboot]

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  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@coreboot.org
> https://www.coreboot.org/mailman/listinfo/coreboot
>



-- 
David Hendricks (dhendrix)
Systems Software Engineer, Google Inc.
-- 
coreboot mailing list: coreboot@coreboot.org
https://www.coreboot.org/mailman/listinfo/coreboot

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

[Nico Huber]

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@coreboot.org
https://www.coreboot.org/mailman/listinfo/coreboot

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

[Matt DeVillier]

agree w/Julius as well.  > 2 lines use verbose seems like a reasonable rule.

On Fri, Aug 26, 2016 at 10:56 AM, 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.
>
> --vb
>
> On Fri, Aug 26, 2016 at 8:48 AM, Martin Roth  wrote:
>
>> Can we please just decide on some tool and setting that we can run all
>> the changes through that will "correctly" format it so we can stop arguing
>> about the format?
>>
>>
>> Martin
>>
>> On Thu, Aug 25, 2016 at 12:59 PM, Julius Werner 
>> wrote:
>>
>>> First of all, let's dispel the notion that there was one "correct" and
>>> one "wrong" comment style in coreboot right now.
>>>
>>> If we count the amount of multi-line comments in the concise style
>>>
>>> > coreboot $ egrep '^\s*/\* [^/]+$' src/ | wc
>>> > 5230 50584 491997
>>>
>>> against the amount of multi-line comments in the verbose style
>>>
>>> > coreboot $ egrep '^\s*/\*$' src/ | wc
>>> > 16103   18607  827285
>>>
>>> and subtract the counts from the FSF license header from that, which
>>> uses the verbose style and is just copy into every file
>>>
>>> > coreboot $ grep 'FITNESS FOR A PARTICULAR PURPOSE' src/ | wc
>>> > 11857  133958 1424055
>>>
>>> we find that the concise style is actually more common in coreboot
>>> right now. I find the idea of overruling thousands of instances of
>>> established practice on behalf of some ancient Wiki text that the
>>> author obviously didn't even read before copy it in there
>>> kinda ridiculous.
>>>
>>> Secondly, Linux cannot even decide for itself which comment style they
>>> prefer (as exemplified by their net/ directory exemption, which they
>>> have maintained for years despite the fact that enforcing different
>>> styles in different parts of the repo is truly crazy), so I don't
>>> think "do what Linux does because Linux is obviously always right"
>>> makes much sense here either. As far as I can tell, they also don't
>>> have any reasonable justification for their decision other than "it's
>>> what Linus (and the net/ maintainer) like". If we really wanted to
>>> blindly follow the Linux way here, we'd have to pick one directory
>>> under coreboot/src/ that arbitrarily enforces a different style than
>>> the others for no reason whatsoever.
>>>
>>> Look, I'm not saying that we should only be using the concise style.
>>> I'm just saying that both styles have their valid uses and we
>>> shouldn't be forcing one over the other in every possible case. Yes,
>>> the verbose style separates comments and makes them stand out better,
>>> and sometimes that's a good and desirable thing! If you want to put in
>>> a big explanation that applies to a whole code block or something, it
>>> may well be the better choice.
>>>
>>> But in other cases you maybe just want to explain a tricky detail
>>> about a single statement in a way that you can't quite fit it on one
>>> line, and forcing people to waste four lines and disrupt the whole
>>> flow of the reader at a point where this wouldn't make sense is not a
>>> good decision in that case. It would be similar to decreeing something
>>> like "there may be at most three statements in a row without a blank
>>> line in between them"... yes, blank lines often increase readability
>>> and are encouraged by our coding style, but only in places that make
>>> sense in the context of the code. Screen real estate is a real thing
>>> and can make an already complicated piece of code way harder to
>>> understand because you can't fit it all on one screen anymore. We'd be
>>> actively making code less readable by forcing such an inflexible
>>> style.
>>>
>>> All I'm saying is that the programmer writing the comment and the
>>> surrounding code probably has a better idea about which amount of
>>> blank space would make it most readable and understandable than some
>>> outdated Wiki page, so this decision should be left to them. We're
>>> writing comments with the explicit intention of helping others
>>> understand our code, after all, so we're naturally going to write them
>>> with the style that works best for each individual case. Forcing the
>>> verbose style everywhere would just cause people to unnecessarily
>>> shorten comments to one line when a big 4+ multi-line comment would be
>>> too disruptive to readability, and thus decrease the overall quality
>>> of our comments.
>>>
>>> --
>>> coreboot mailing list: coreboot@coreboot.org
>>> https://www.coreboot.org/mailman/listinfo/coreboot
>>>
>>
>>
>> --
>> coreboot mailing list: coreboot@coreboot.org
>> https://www.coreboot.org/mailman/listinfo/coreboot
>>
>
>
> --
> coreboot mailing list: coreboot@coreboot.org
> https://www.coreboot.org/mailman/listinfo/coreboot
>
-- 
coreboot mailing list: coreboot@coreboot.org

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

[Martin Roth]

And I don't really care either way.  Let's either update the documentation
or follow it though.

If we have coding standards, let's follow them.  If we feel like the
individual programmer knows best for everything, let's SAY that so I can
stop trying to fix whitespace in the reviews.



On Fri, Aug 26, 2016 at 9:56 AM, 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.
>
> --vb
>
> On Fri, Aug 26, 2016 at 8:48 AM, Martin Roth  wrote:
>
>> Can we please just decide on some tool and setting that we can run all
>> the changes through that will "correctly" format it so we can stop arguing
>> about the format?
>>
>>
>> Martin
>>
>> On Thu, Aug 25, 2016 at 12:59 PM, Julius Werner 
>> wrote:
>>
>>> First of all, let's dispel the notion that there was one "correct" and
>>> one "wrong" comment style in coreboot right now.
>>>
>>> If we count the amount of multi-line comments in the concise style
>>>
>>> > coreboot $ egrep '^\s*/\* [^/]+$' src/ | wc
>>> > 5230 50584 491997
>>>
>>> against the amount of multi-line comments in the verbose style
>>>
>>> > coreboot $ egrep '^\s*/\*$' src/ | wc
>>> > 16103   18607  827285
>>>
>>> and subtract the counts from the FSF license header from that, which
>>> uses the verbose style and is just copy into every file
>>>
>>> > coreboot $ grep 'FITNESS FOR A PARTICULAR PURPOSE' src/ | wc
>>> > 11857  133958 1424055
>>>
>>> we find that the concise style is actually more common in coreboot
>>> right now. I find the idea of overruling thousands of instances of
>>> established practice on behalf of some ancient Wiki text that the
>>> author obviously didn't even read before copy it in there
>>> kinda ridiculous.
>>>
>>> Secondly, Linux cannot even decide for itself which comment style they
>>> prefer (as exemplified by their net/ directory exemption, which they
>>> have maintained for years despite the fact that enforcing different
>>> styles in different parts of the repo is truly crazy), so I don't
>>> think "do what Linux does because Linux is obviously always right"
>>> makes much sense here either. As far as I can tell, they also don't
>>> have any reasonable justification for their decision other than "it's
>>> what Linus (and the net/ maintainer) like". If we really wanted to
>>> blindly follow the Linux way here, we'd have to pick one directory
>>> under coreboot/src/ that arbitrarily enforces a different style than
>>> the others for no reason whatsoever.
>>>
>>> Look, I'm not saying that we should only be using the concise style.
>>> I'm just saying that both styles have their valid uses and we
>>> shouldn't be forcing one over the other in every possible case. Yes,
>>> the verbose style separates comments and makes them stand out better,
>>> and sometimes that's a good and desirable thing! If you want to put in
>>> a big explanation that applies to a whole code block or something, it
>>> may well be the better choice.
>>>
>>> But in other cases you maybe just want to explain a tricky detail
>>> about a single statement in a way that you can't quite fit it on one
>>> line, and forcing people to waste four lines and disrupt the whole
>>> flow of the reader at a point where this wouldn't make sense is not a
>>> good decision in that case. It would be similar to decreeing something
>>> like "there may be at most three statements in a row without a blank
>>> line in between them"... yes, blank lines often increase readability
>>> and are encouraged by our coding style, but only in places that make
>>> sense in the context of the code. Screen real estate is a real thing
>>> and can make an already complicated piece of code way harder to
>>> understand because you can't fit it all on one screen anymore. We'd be
>>> actively making code less readable by forcing such an inflexible
>>> style.
>>>
>>> All I'm saying is that the programmer writing the comment and the
>>> surrounding code probably has a better idea about which amount of
>>> blank space would make it most readable and understandable than some
>>> outdated Wiki page, so this decision should be left to them. We're
>>> writing comments with the explicit intention of helping others
>>> understand our code, after all, so we're naturally going to write them
>>> with the style that works best for each individual case. Forcing the
>>> verbose style everywhere would just cause people to unnecessarily
>>> shorten comments to one line when a big 4+ multi-line comment would be
>>> too disruptive to readability, and thus decrease the overall quality
>>> of our comments.
>>>
>>> --
>>> coreboot mailing list: coreboot@coreboot.org
>>> https://www.coreboot.org/mailman/listinfo/coreboot
>>>
>>
>>
>> --
>> coreboot mailing list: coreboot@coreboot.org
>> 

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

[Vadim Bendebury]

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.

--vb

On Fri, Aug 26, 2016 at 8:48 AM, Martin Roth  wrote:

> Can we please just decide on some tool and setting that we can run all the
> changes through that will "correctly" format it so we can stop arguing
> about the format?
>
>
> Martin
>
> On Thu, Aug 25, 2016 at 12:59 PM, Julius Werner 
> wrote:
>
>> First of all, let's dispel the notion that there was one "correct" and
>> one "wrong" comment style in coreboot right now.
>>
>> If we count the amount of multi-line comments in the concise style
>>
>> > coreboot $ egrep '^\s*/\* [^/]+$' src/ | wc
>> > 5230 50584 491997
>>
>> against the amount of multi-line comments in the verbose style
>>
>> > coreboot $ egrep '^\s*/\*$' src/ | wc
>> > 16103   18607  827285
>>
>> and subtract the counts from the FSF license header from that, which
>> uses the verbose style and is just copy into every file
>>
>> > coreboot $ grep 'FITNESS FOR A PARTICULAR PURPOSE' src/ | wc
>> > 11857  133958 1424055
>>
>> we find that the concise style is actually more common in coreboot
>> right now. I find the idea of overruling thousands of instances of
>> established practice on behalf of some ancient Wiki text that the
>> author obviously didn't even read before copy it in there
>> kinda ridiculous.
>>
>> Secondly, Linux cannot even decide for itself which comment style they
>> prefer (as exemplified by their net/ directory exemption, which they
>> have maintained for years despite the fact that enforcing different
>> styles in different parts of the repo is truly crazy), so I don't
>> think "do what Linux does because Linux is obviously always right"
>> makes much sense here either. As far as I can tell, they also don't
>> have any reasonable justification for their decision other than "it's
>> what Linus (and the net/ maintainer) like". If we really wanted to
>> blindly follow the Linux way here, we'd have to pick one directory
>> under coreboot/src/ that arbitrarily enforces a different style than
>> the others for no reason whatsoever.
>>
>> Look, I'm not saying that we should only be using the concise style.
>> I'm just saying that both styles have their valid uses and we
>> shouldn't be forcing one over the other in every possible case. Yes,
>> the verbose style separates comments and makes them stand out better,
>> and sometimes that's a good and desirable thing! If you want to put in
>> a big explanation that applies to a whole code block or something, it
>> may well be the better choice.
>>
>> But in other cases you maybe just want to explain a tricky detail
>> about a single statement in a way that you can't quite fit it on one
>> line, and forcing people to waste four lines and disrupt the whole
>> flow of the reader at a point where this wouldn't make sense is not a
>> good decision in that case. It would be similar to decreeing something
>> like "there may be at most three statements in a row without a blank
>> line in between them"... yes, blank lines often increase readability
>> and are encouraged by our coding style, but only in places that make
>> sense in the context of the code. Screen real estate is a real thing
>> and can make an already complicated piece of code way harder to
>> understand because you can't fit it all on one screen anymore. We'd be
>> actively making code less readable by forcing such an inflexible
>> style.
>>
>> All I'm saying is that the programmer writing the comment and the
>> surrounding code probably has a better idea about which amount of
>> blank space would make it most readable and understandable than some
>> outdated Wiki page, so this decision should be left to them. We're
>> writing comments with the explicit intention of helping others
>> understand our code, after all, so we're naturally going to write them
>> with the style that works best for each individual case. Forcing the
>> verbose style everywhere would just cause people to unnecessarily
>> shorten comments to one line when a big 4+ multi-line comment would be
>> too disruptive to readability, and thus decrease the overall quality
>> of our comments.
>>
>> --
>> coreboot mailing list: coreboot@coreboot.org
>> https://www.coreboot.org/mailman/listinfo/coreboot
>>
>
>
> --
> coreboot mailing list: coreboot@coreboot.org
> https://www.coreboot.org/mailman/listinfo/coreboot
>
-- 
coreboot mailing list: coreboot@coreboot.org
https://www.coreboot.org/mailman/listinfo/coreboot

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

[Martin Roth]

Can we please just decide on some tool and setting that we can run all the
changes through that will "correctly" format it so we can stop arguing
about the format?


Martin

On Thu, Aug 25, 2016 at 12:59 PM, Julius Werner 
wrote:

> First of all, let's dispel the notion that there was one "correct" and
> one "wrong" comment style in coreboot right now.
>
> If we count the amount of multi-line comments in the concise style
>
> > coreboot $ egrep '^\s*/\* [^/]+$' src/ | wc
> > 5230 50584 491997
>
> against the amount of multi-line comments in the verbose style
>
> > coreboot $ egrep '^\s*/\*$' src/ | wc
> > 16103   18607  827285
>
> and subtract the counts from the FSF license header from that, which
> uses the verbose style and is just copy into every file
>
> > coreboot $ grep 'FITNESS FOR A PARTICULAR PURPOSE' src/ | wc
> > 11857  133958 1424055
>
> we find that the concise style is actually more common in coreboot
> right now. I find the idea of overruling thousands of instances of
> established practice on behalf of some ancient Wiki text that the
> author obviously didn't even read before copy it in there
> kinda ridiculous.
>
> Secondly, Linux cannot even decide for itself which comment style they
> prefer (as exemplified by their net/ directory exemption, which they
> have maintained for years despite the fact that enforcing different
> styles in different parts of the repo is truly crazy), so I don't
> think "do what Linux does because Linux is obviously always right"
> makes much sense here either. As far as I can tell, they also don't
> have any reasonable justification for their decision other than "it's
> what Linus (and the net/ maintainer) like". If we really wanted to
> blindly follow the Linux way here, we'd have to pick one directory
> under coreboot/src/ that arbitrarily enforces a different style than
> the others for no reason whatsoever.
>
> Look, I'm not saying that we should only be using the concise style.
> I'm just saying that both styles have their valid uses and we
> shouldn't be forcing one over the other in every possible case. Yes,
> the verbose style separates comments and makes them stand out better,
> and sometimes that's a good and desirable thing! If you want to put in
> a big explanation that applies to a whole code block or something, it
> may well be the better choice.
>
> But in other cases you maybe just want to explain a tricky detail
> about a single statement in a way that you can't quite fit it on one
> line, and forcing people to waste four lines and disrupt the whole
> flow of the reader at a point where this wouldn't make sense is not a
> good decision in that case. It would be similar to decreeing something
> like "there may be at most three statements in a row without a blank
> line in between them"... yes, blank lines often increase readability
> and are encouraged by our coding style, but only in places that make
> sense in the context of the code. Screen real estate is a real thing
> and can make an already complicated piece of code way harder to
> understand because you can't fit it all on one screen anymore. We'd be
> actively making code less readable by forcing such an inflexible
> style.
>
> All I'm saying is that the programmer writing the comment and the
> surrounding code probably has a better idea about which amount of
> blank space would make it most readable and understandable than some
> outdated Wiki page, so this decision should be left to them. We're
> writing comments with the explicit intention of helping others
> understand our code, after all, so we're naturally going to write them
> with the style that works best for each individual case. Forcing the
> verbose style everywhere would just cause people to unnecessarily
> shorten comments to one line when a big 4+ multi-line comment would be
> too disruptive to readability, and thus decrease the overall quality
> of our comments.
>
> --
> coreboot mailing list: coreboot@coreboot.org
> https://www.coreboot.org/mailman/listinfo/coreboot
>
-- 
coreboot mailing list: coreboot@coreboot.org
https://www.coreboot.org/mailman/listinfo/coreboot

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

[Julius Werner]

First of all, let's dispel the notion that there was one "correct" and
one "wrong" comment style in coreboot right now.

If we count the amount of multi-line comments in the concise style

> coreboot $ egrep '^\s*/\* [^/]+$' src/ | wc
> 5230 50584 491997

against the amount of multi-line comments in the verbose style

> coreboot $ egrep '^\s*/\*$' src/ | wc
> 16103   18607  827285

and subtract the counts from the FSF license header from that, which
uses the verbose style and is just copy into every file

> coreboot $ grep 'FITNESS FOR A PARTICULAR PURPOSE' src/ | wc
> 11857  133958 1424055

we find that the concise style is actually more common in coreboot
right now. I find the idea of overruling thousands of instances of
established practice on behalf of some ancient Wiki text that the
author obviously didn't even read before copy it in there
kinda ridiculous.

Secondly, Linux cannot even decide for itself which comment style they
prefer (as exemplified by their net/ directory exemption, which they
have maintained for years despite the fact that enforcing different
styles in different parts of the repo is truly crazy), so I don't
think "do what Linux does because Linux is obviously always right"
makes much sense here either. As far as I can tell, they also don't
have any reasonable justification for their decision other than "it's
what Linus (and the net/ maintainer) like". If we really wanted to
blindly follow the Linux way here, we'd have to pick one directory
under coreboot/src/ that arbitrarily enforces a different style than
the others for no reason whatsoever.

Look, I'm not saying that we should only be using the concise style.
I'm just saying that both styles have their valid uses and we
shouldn't be forcing one over the other in every possible case. Yes,
the verbose style separates comments and makes them stand out better,
and sometimes that's a good and desirable thing! If you want to put in
a big explanation that applies to a whole code block or something, it
may well be the better choice.

But in other cases you maybe just want to explain a tricky detail
about a single statement in a way that you can't quite fit it on one
line, and forcing people to waste four lines and disrupt the whole
flow of the reader at a point where this wouldn't make sense is not a
good decision in that case. It would be similar to decreeing something
like "there may be at most three statements in a row without a blank
line in between them"... yes, blank lines often increase readability
and are encouraged by our coding style, but only in places that make
sense in the context of the code. Screen real estate is a real thing
and can make an already complicated piece of code way harder to
understand because you can't fit it all on one screen anymore. We'd be
actively making code less readable by forcing such an inflexible
style.

All I'm saying is that the programmer writing the comment and the
surrounding code probably has a better idea about which amount of
blank space would make it most readable and understandable than some
outdated Wiki page, so this decision should be left to them. We're
writing comments with the explicit intention of helping others
understand our code, after all, so we're naturally going to write them
with the style that works best for each individual case. Forcing the
verbose style everywhere would just cause people to unnecessarily
shorten comments to one line when a big 4+ multi-line comment would be
too disruptive to readability, and thus decrease the overall quality
of our comments.

-- 
coreboot mailing list: coreboot@coreboot.org
https://www.coreboot.org/mailman/listinfo/coreboot

Re: [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@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 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@coreboot.org
> https://www.coreboot.org/mailman/listinfo/coreboot
>
-- 
coreboot mailing list: coreboot@coreboot.org
https://www.coreboot.org/mailman/listinfo/coreboot

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

[Paul Menzel via coreboot]

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

signature.asc
Description: This is a digitally signed message part
-- 
coreboot mailing list: coreboot@coreboot.org
https://www.coreboot.org/mailman/listinfo/coreboot