-
Notifications
You must be signed in to change notification settings - Fork 29.8k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
doc: formalize auto
usage in C++ style guide
#23028
Conversation
4395d62
to
650305a
Compare
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Conflicts with google style guide & C++ Core Guidelines
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Conflicts with google style guide & C++ Core Guidelines
CPP_STYLE_GUIDE.md
Outdated
## Do not include `*.h` if `*-inl.h` has already been included | ||
### Using `auto` | ||
|
||
Being explicit about types is preferred over using `auto`. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yes please!
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
One of the main benefits of adopting an established style guide is to reduce bikeshedding. I recommend the following talk by Herb Sutter (head of the c++ ISO group) https://www.youtube.com/watch?v=hEx5DNLWGgA
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I've also found auto
convenient and helpful when the type is obvious from context... e.g.
auto traced_value = tracing::TracedValue::Create();
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@refack Just realized I watched the same argument made by Herb Sutter in 2014 back in 2015 but still my experience in real-world code bases taught me otherwise...not that I am completely against auto
, though, but I still prefer explicit types when it helps with readability, especially in code reviews where the diff may be out of context and there is no IDE to help analyzing the types.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@jasnell Even in that example one would have to look up what Create()
actually returns… for example, it could definitely be either a smart pointer or a regular pointer.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think the point is to reduce "clutter" and allow the reader to focus on the intent of the code.
In most cases the exact type of (for example) traced_value
is probably not relevant for review purposes, it might even be a distraction from what the code actually does. From the idea that the more we have to read, we have less focus on the actual point of the change.
After all that is what 100% of code in JS looks like and we manage excellently.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think the point is to reduce "clutter" and allow the reader to focus on the intent of the code.
There are other measures, though – in particular, correctness is an important one. By requesting more explicit types, we put that before focusing on intent (as in this example).
After all that is what 100% of code in JS looks like and we manage excellently.
If that were completely true, things like TypeScript wouldn’t exist – which is something that’s used by 46 % of npm users, after all, and the added correctness guarantees are definitely a major reason for that.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
After all that is what 100% of code in JS looks like and we manage excellently.
Not necessarily, for properties and a lot of local variables we initialize them upfront so in the declaration it's already very clear what their types are supposed to be. Personally I would want to see more JSDoc-like annotations in lib
(not necessary for simple helpers, but would be very helpful for functions with a lot of arguments named with something like obj
, value
, handle
, .etc).
I was just about to suggest the opposite, on both clauses. They are both counter-idiomatic with "modern" C++ (c++11 and higher).
From the Google style guide:
Both guides have specific rules for function arguments:
|
tl;dr IMHO we should improve our style and guidelines by learning from experienced source in order to improve our code correctness, readability, maintainability, and reduce the entry barrier. |
@refack The sections about
And the
In the C++ Core Guidelines
They both bring up templates as examples where using |
I can’t find anything on local (non-parameter) references in the Google style guide, but the policy you linked to is in agreement with this PR for function parameters. I’ve also only very rarely at best seen non-const references in the V8 or Chromium sources. |
But the current suggestion is |
I'll give an example that came up during review: for (std::string::size_type i = 0; i < name.size(); ++i) {
if (name[i] == '_')
name[i] = '-';
} or for (auto& i : name) {
if (i == '_')
i = '-';
} Which would be easier for a newcomer to understand? Which one give the compiler more chances to validate the code, and optimize the binary? |
Total serendipity, I stumbled upon this talk about what compilers actually do for these loops, and what they are optimizing |
I’m not sure about the others around here, but from the people who review a lot of C++ code on a regular basis, both @joyeecheung and me seem to think that this would impact reviewability and readability negatively.
Honestly, I think it depends, both on how “new” the newcomer is and what exactly “understand” means here. The for-range +
Both should result in similar code – but we shouldn’t even bother worrying about this question in code that is not performance-critical. |
I'm not sure what you meant by that, it reads to me like you want that group to stay small and exclusive? BTW my formal education and experience is in "classic" C++, and all this "modern" stuff is completely new, and still groking our current C++ code IMHO is too hard. IMHO if our coding guidelines were more in line with established guides (i.e. what you can learn in books and courses, as opposed to word of mouth kept by a small group), the group of C++ writers and reviewers could more more inclusive. |
Is this ( |
I don’t know how you came to that conclusion based on what I said. If anything, it’s the opposite – I’d love for the number of people who work on and with our C++ code base to increase. That would make both my life easier and improve Node’s quality on its own. I’m not sure how to rephrase the above sentence, though. What I meant is that from the existing frequent reviewers, two of us have, based on our experience, come to the conclusion that your suggestion would likely not be an improvement if readability and reviewability are the values by which we judge it. I’d be happy for other people to share their experience as well.
Just to clarify how this relates to the current argument – are you saying these rules would make understanding existing code easier for you? I understand that our code base is not the most easily accessible one, but as far as I can tell, the main issues that people have are around concepts that are specific to V8 or libuv.
Our guidelines are quite close to the Google ones that you also refer to, especially with regards to the particular items that we’re discussing here.
Yeah, it is neither – for example, the rules here can’t be enforced through formatting alone. |
@addaleax ... I'm happy with everything in this except the bits about auto. Do you think it would be possible to separate that one bit out to a separate PR that we can discuss separately without blocking the rest of this? On the auto part, I think we should likely be more explicit about the cases where it's ok. With some examples included. |
@jasnell It looks like this PR is going to be blocked as a whole anyway… I’ll split out the first commit, though, so that we can split the I’ve also updated the text on |
Adjust heading levels to align with the table of contents. Refs: nodejs#23028 Reviewed-By: Tobias Nießen <tniessen@tnie.de> Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com> Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com> Reviewed-By: Daniel Bevenius <daniel.bevenius@gmail.com>
0fc3c63
to
1a97e31
Compare
Adjust heading levels to align with the table of contents. Refs: nodejs#23028 PR-URL: nodejs#23061 Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com> Reviewed-By: Refael Ackermann <refack@gmail.com> Reviewed-By: Tobias Nießen <tniessen@tnie.de> Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com> Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com> Reviewed-By: Daniel Bevenius <daniel.bevenius@gmail.com>
Adjust heading levels to align with the table of contents. Refs: #23028 PR-URL: #23061 Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com> Reviewed-By: Refael Ackermann <refack@gmail.com> Reviewed-By: Tobias Nießen <tniessen@tnie.de> Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com> Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com> Reviewed-By: Daniel Bevenius <daniel.bevenius@gmail.com>
I believe you are correct, |
Thank you |
Landed in aba7677 |
We generally avoid using `auto` if not necessary. This formalizes this rules by writing them down in the C++ style guide. PR-URL: #23028 Reviewed-By: Tobias Nießen <tniessen@tnie.de> Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Refael Ackermann <refack@gmail.com> Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com> Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com> Reviewed-By: Daniel Bevenius <daniel.bevenius@gmail.com> Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com> Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
We generally avoid using `auto` if not necessary. This formalizes this rules by writing them down in the C++ style guide. PR-URL: #23028 Reviewed-By: Tobias Nießen <tniessen@tnie.de> Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Refael Ackermann <refack@gmail.com> Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com> Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com> Reviewed-By: Daniel Bevenius <daniel.bevenius@gmail.com> Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com> Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
We generally avoid using `auto` if not necessary. This formalizes this rules by writing them down in the C++ style guide. PR-URL: #23028 Reviewed-By: Tobias Nießen <tniessen@tnie.de> Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Refael Ackermann <refack@gmail.com> Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com> Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com> Reviewed-By: Daniel Bevenius <daniel.bevenius@gmail.com> Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com> Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
We generally avoid using non-const references if not necessary. This formalizes this rules by writing them down in the C++ style guide. (Note: Some reviews are from the original PR.) Refs: #23028 PR-URL: #23155 Reviewed-By: Tobias Nießen <tniessen@tnie.de> Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com> Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com> Reviewed-By: Daniel Bevenius <daniel.bevenius@gmail.com> Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com> Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com> Reviewed-By: Refael Ackermann <refack@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Michaël Zasso <targos@protonmail.com> Reviewed-By: Ali Ijaz Sheikh <ofrobots@google.com> Reviewed-By: Anatoli Papirovski <apapirovski@mac.com>
We generally avoid using non-const references if not necessary. This formalizes this rules by writing them down in the C++ style guide. (Note: Some reviews are from the original PR.) Refs: #23028 PR-URL: #23155 Reviewed-By: Tobias Nießen <tniessen@tnie.de> Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com> Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com> Reviewed-By: Daniel Bevenius <daniel.bevenius@gmail.com> Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com> Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com> Reviewed-By: Refael Ackermann <refack@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Michaël Zasso <targos@protonmail.com> Reviewed-By: Ali Ijaz Sheikh <ofrobots@google.com> Reviewed-By: Anatoli Papirovski <apapirovski@mac.com>
We generally avoid using non-const references if not necessary. This formalizes this rules by writing them down in the C++ style guide. (Note: Some reviews are from the original PR.) Refs: #23028 PR-URL: #23155 Reviewed-By: Tobias Nießen <tniessen@tnie.de> Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com> Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com> Reviewed-By: Daniel Bevenius <daniel.bevenius@gmail.com> Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com> Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com> Reviewed-By: Refael Ackermann <refack@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Michaël Zasso <targos@protonmail.com> Reviewed-By: Ali Ijaz Sheikh <ofrobots@google.com> Reviewed-By: Anatoli Papirovski <apapirovski@mac.com>
We generally avoid using non-const references if not necessary. This formalizes this rules by writing them down in the C++ style guide. (Note: Some reviews are from the original PR.) Refs: #23028 PR-URL: #23155 Reviewed-By: Tobias Nießen <tniessen@tnie.de> Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com> Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com> Reviewed-By: Daniel Bevenius <daniel.bevenius@gmail.com> Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com> Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com> Reviewed-By: Refael Ackermann <refack@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Michaël Zasso <targos@protonmail.com> Reviewed-By: Ali Ijaz Sheikh <ofrobots@google.com> Reviewed-By: Anatoli Papirovski <apapirovski@mac.com>
We generally avoid using non-const references if not necessary. This formalizes this rules by writing them down in the C++ style guide. (Note: Some reviews are from the original PR.) Refs: #23028 PR-URL: #23155 Reviewed-By: Tobias Nießen <tniessen@tnie.de> Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com> Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com> Reviewed-By: Daniel Bevenius <daniel.bevenius@gmail.com> Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com> Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com> Reviewed-By: Refael Ackermann <refack@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Michaël Zasso <targos@protonmail.com> Reviewed-By: Ali Ijaz Sheikh <ofrobots@google.com> Reviewed-By: Anatoli Papirovski <apapirovski@mac.com>
Adjust heading levels to align with the table of contents, and write down 2 more existing rules (avoiding non-const references andauto
under most circumstances).We generally avoid using
auto
if not necessary. This formalizes this rules by writing them down in the C++ style guide.The other part of the PR has been split out into #23155.
Checklist
make -j4 test
(UNIX), orvcbuild test
(Windows) passes