Hi all,
As application of the naming rules are currently under discussion [1] this seems
like a good time to bring this up:
The current variable naming rule [2] states: Variable names should be nouns (as
they represent state). The name should be camel case, and start with an upper
case letter (e.g. Leader or Boats).
I'm a relatively new arrival to the LLVM codebase and I want to follow the
rules wherever I can, but I humbly submit that this rule is suboptimal for
readable code.
The rationale given at the time this rule was added was "document the
prevailing convention" [3]. It was debated after the policy change whether
this was the right choice [4].
The main problem I find with this rule is that it is the same as the type naming
rule. Why is this a problem? It is famously hard to name things ("There are
2 hard problems in computer science: cache invalidation, naming things, and
off-by-1 errors.") and with this rule if you've already used a name for
a type, you can't reuse it for a variable of that type.
So what do you do instead? Often it seems the answer is to use an acronym
(Target T), which hurts readability, or prepend "The" to the type name
(Target TheTarget), which wastes space and also hurts readability because the
start and end of a word are the most important for readnig. [5]
So we've got declarations like "LB(L, PSE, LI, DT, TLI, TTI, AC, ORE,
VF.Width, IC, &LVL, &CM)" [6] which is quite intimidating to
newcomers.
If we could also use snake_case variable names then straight away you have an
obvious, readable name (Target target). It looks like there's plenty of code
that does this already, and it's consistent with our Python code. Also, it
makes C idioms like "for (int i = 0; ..." permissible.
I realize that there's also a rule [2] "Avoid abbreviations unless they
are well known" - I believe allowing a trivial way to get readable names
would help greatly to adhere to this.
What do you think? Could we relax the variable naming rule?
[1] http://lists.llvm.org/pipermail/cfe-dev/2019-January/061085.html
[2]
https://llvm.org/docs/CodingStandards.html#name-types-functions-variables-and-enumerators-properly
[3]
https://github.com/llvm/llvm-project/commit/30e697ebaf4fc8a9b8cf6abecbc75ef1b9fa0dc0
[4]
http://lists.llvm.org/pipermail/llvm-commits/Week-of-Mon-20110808/126097.html
[5] Mostly based on my own experience, but somewhat supported by evidence:
https://en.wikipedia.org/wiki/Transposed_letter_effect
[6]
https://github.com/llvm/llvm-project/blob/master/llvm/lib/Transforms/Vectorize/LoopVectorize.cpp#L7433
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.llvm.org/pipermail/llvm-dev/attachments/20190201/6d18516c/attachment-0001.html>
Is moving to snake_case and the resulting inconsistency in the naming conventions worth the benefits? A wholesome change is out of the question. Amara> On 1 Feb 2019, at 06:20, Michael Platings via llvm-dev <llvm-dev at lists.llvm.org> wrote: > > Hi all, > > As application of the naming rules are currently under discussion [1] this seems like a good time to bring this up: > > The current variable naming rule [2] states: Variable names should be nouns (as they represent state). The name should be camel case, and start with an upper case letter (e.g. Leader or Boats). > I'm a relatively new arrival to the LLVM codebase and I want to follow the rules wherever I can, but I humbly submit that this rule is suboptimal for readable code. > The rationale given at the time this rule was added was "document the prevailing convention" [3]. It was debated after the policy change whether this was the right choice [4]. > The main problem I find with this rule is that it is the same as the type naming rule. Why is this a problem? It is famously hard to name things ("There are 2 hard problems in computer science: cache invalidation, naming things, and off-by-1 errors.") and with this rule if you've already used a name for a type, you can't reuse it for a variable of that type. > So what do you do instead? Often it seems the answer is to use an acronym (Target T), which hurts readability, or prepend "The" to the type name (Target TheTarget), which wastes space and also hurts readability because the start and end of a word are the most important for readnig. [5] > > So we've got declarations like "LB(L, PSE, LI, DT, TLI, TTI, AC, ORE, VF.Width, IC, &LVL, &CM)" [6] which is quite intimidating to newcomers. > > If we could also use snake_case variable names then straight away you have an obvious, readable name (Target target). It looks like there's plenty of code that does this already, and it's consistent with our Python code. Also, it makes C idioms like "for (int i = 0; ..." permissible. > > I realize that there's also a rule [2] "Avoid abbreviations unless they are well known" - I believe allowing a trivial way to get readable names would help greatly to adhere to this. > What do you think? Could we relax the variable naming rule? > > [1] http://lists.llvm.org/pipermail/cfe-dev/2019-January/061085.html <http://lists.llvm.org/pipermail/cfe-dev/2019-January/061085.html> > [2] https://llvm.org/docs/CodingStandards.html#name-types-functions-variables-and-enumerators-properly <https://llvm.org/docs/CodingStandards.html#name-types-functions-variables-and-enumerators-properly> > [3] https://github.com/llvm/llvm-project/commit/30e697ebaf4fc8a9b8cf6abecbc75ef1b9fa0dc0 <https://github.com/llvm/llvm-project/commit/30e697ebaf4fc8a9b8cf6abecbc75ef1b9fa0dc0> > [4] http://lists.llvm.org/pipermail/llvm-commits/Week-of-Mon-20110808/126097.html <http://lists.llvm.org/pipermail/llvm-commits/Week-of-Mon-20110808/126097.html> > [5] Mostly based on my own experience, but somewhat supported by evidence:https://en.wikipedia.org/wiki/Transposed_letter_effect <https://en.wikipedia.org/wiki/Transposed_letter_effect> > [6] https://github.com/llvm/llvm-project/blob/master/llvm/lib/Transforms/Vectorize/LoopVectorize.cpp#L7433 <https://github.com/llvm/llvm-project/blob/master/llvm/lib/Transforms/Vectorize/LoopVectorize.cpp#L7433>_______________________________________________ > LLVM Developers mailing list > llvm-dev at lists.llvm.org <mailto:llvm-dev at lists.llvm.org> > https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev <https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev>-------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20190201/464174fd/attachment.html>
On Sat, 2 Feb 2019 at 02:49, Amara Emerson via llvm-dev <llvm-dev at lists.llvm.org> wrote:> Is moving to snake_case and the resulting inconsistency in the naming conventions worth the benefits? A wholesome change is out of the question.With the move to GitHub we have a once in a lifetime opportunity to rewrite history into a preferred, consistent form. And I'm only 90% joking there. Tim.
> On Feb 1, 2019, at 6:20 AM, Michael Platings via llvm-dev <llvm-dev at lists.llvm.org> wrote: > > Hi all, > > As application of the naming rules are currently under discussion [1] this seems like a good time to bring this up: > > The current variable naming rule [2] states: Variable names should be nouns (as they represent state). The name should be camel case, and start with an upper case letter (e.g. Leader or Boats). > I'm a relatively new arrival to the LLVM codebase and I want to follow the rules wherever I can, but I humbly submit that this rule is suboptimal for readable code. > The rationale given at the time this rule was added was "document the prevailing convention" [3].I completely agree with you that our variable naming rule is broken. This discussion has been brought up before (e.g. http://lists.llvm.org/pipermail/llvm-dev/2014-October/077685.html <http://lists.llvm.org/pipermail/llvm-dev/2014-October/077685.html>) and hasn’t made any progress - people seem to not be willing to make a change, e.g. saying "the cure is worse than the disease". I’m personally in favor of Nick’s proposal (linked above) which makes variable names and function names be lower camel case. The Swift language world (a developer community several orders of magnitude larger than LLVM’s) uses this convention very successfully and people seem very happy with it. Swift also has a very carefully considered API design guide (https://swift.org/documentation/api-design-guidelines/ <https://swift.org/documentation/api-design-guidelines/>), which applies quite well to C++ APIs as well. If you haven’t seen it, it is worth a look. Using camel case for one thing and snake case for another is too weird IMO. Even if the community does not have the appetite to do a huge scale renaming of all the things in LLVM, it would be interesting to carve out an exception for new code being written, refactored, or potentially for use in new subprojects. -Chris -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20190202/4a3dfda0/attachment.html>
> On Feb 2, 2019, at 8:18 PM, Chris Lattner <clattner at nondot.org> wrote: > > > >> On Feb 1, 2019, at 6:20 AM, Michael Platings via llvm-dev <llvm-dev at lists.llvm.org <mailto:llvm-dev at lists.llvm.org>> wrote: >> >> Hi all, >> >> As application of the naming rules are currently under discussion [1] this seems like a good time to bring this up: >> >> The current variable naming rule [2] states: Variable names should be nouns (as they represent state). The name should be camel case, and start with an upper case letter (e.g. Leader or Boats). >> I'm a relatively new arrival to the LLVM codebase and I want to follow the rules wherever I can, but I humbly submit that this rule is suboptimal for readable code. >> The rationale given at the time this rule was added was "document the prevailing convention" [3]. > > I completely agree with you that our variable naming rule is broken. This discussion has been brought up before (e.g. http://lists.llvm.org/pipermail/llvm-dev/2014-October/077685.html <http://lists.llvm.org/pipermail/llvm-dev/2014-October/077685.html>) and hasn’t made any progress - people seem to not be willing to make a change, e.g. saying "the cure is worse than the disease". I’m personally in favor of Nick’s proposal (linked above) which makes variable names and function names be lower camel case.It’s worth noting that at the time, if I recall correctly, I argued against Nick’s proposal. I’m since come around to see the wisdom of his position and agree that we should have done it. -Chris -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20190202/96aa9eae/attachment.html>