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 <[email protected]> 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 <[email protected]> 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 <[email protected]> >> 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&pasted 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&pasting 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: [email protected] >>> https://www.coreboot.org/mailman/listinfo/coreboot >>> >> >> >> -- >> coreboot mailing list: [email protected] >> https://www.coreboot.org/mailman/listinfo/coreboot >> > > > -- > coreboot mailing list: [email protected] > https://www.coreboot.org/mailman/listinfo/coreboot >
-- coreboot mailing list: [email protected] https://www.coreboot.org/mailman/listinfo/coreboot
