doc: formalize non-const reference usage in C++ style guide #23155

addaleax · 2018-09-29T01:15:04Z

Split out from #23028 by request from @refack. I’ve added people who approved the other PR as reviewers on the commit. I’m also moving the tsc-agenda label over here, assuming @refack’s objection stands.

We generally avoid using non-const references if not necessary. This
formalizes this rules by writing them down in the C++ style guide.

Checklist

make -j4 test (UNIX), or vcbuild test (Windows) passes
documentation is changed or added
commit message follows commit guidelines

We generally avoid using non-const references if not necessary. This formalizes this rules by writing them down in the C++ style guide. 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> Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com> Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>

nodejs-github-bot · 2018-09-29T01:15:05Z

@addaleax build started: https://ci.nodejs.org/blue/organizations/jenkins/node-test-pull-request-lite-pipeline/detail/node-test-pull-request-lite-pipeline/1056/pipeline

refack

Hoping we can discuss this further, and find middle ground.

refack · 2018-09-29T02:14:34Z

_{Quoting from previous PR:}

I believe non-const reference has been established as the tool to use for idiomatic iterative mutation in "modern" C++ (C++11 and higher).

I'm taking the lead of the C++ ISO committee and the STL designers who decided to use references, and value semantics ahead of pointers. Case in point begin and end return iterators that are convertible to references and not pointers. So to mutate a collection with an STL algorithm, you can only use non-const references:

std::vector<int> nums{3, 4, 2, 8, 15, 267};
std::for_each(nums.begin(), nums.end(), [](int &n){ n++; });

From the C++CG:

P.3: Express intent

...
for (const auto& x : v) { /* do something with the value of x */ }
Now, there is no explicit mention of the iteration mechanism, and the loop operates on a reference to const elements so that accidental modification cannot happen. If modification is desired, say so:
for (auto& x : v) { /* modify x */ }

With code that came up in a code review in our repo, it was presented with a common classical way to do mutation without a reference:

for (std::string::size_type i = 0; i < name.size(); ++i) {
  if (name[i] == '_') 
    name[i] = '-';
}

Compared this with the C++11 idiomatic (read "this is iterating using a reference because the intent is to modify").

for (auto& i : name) {
  if (i == '_') 
    i = '-';
}

So essentially IMHO having "no non-const references" rule, means "no idiomatic mutations".

From a personal perspective, I also agree with a few more arguments in favor of non-const reference:

They can't be uninitialized.
They can't be null, so they fit perfectly to the use case of a variable is not allowed to be null.
They clearly express non-ownership, while with pointers there is still doubt.
They provide the compiler with more optimization opportunities (unless the compiler can to prove you don't need a pointer, it will have to allocate space for it).
IMHO they are simpler to understand. Grokking pointers requires always keeping another level of indirection in mind.

BTW, both guides do have limits, spesificly WRT to function arguments:

Google Reference Arguments - All parameters passed by lvalue reference must be labeled const.
F.16: For “in” parameters, pass cheaply-copied types by value and others by reference to const
F.17: For “in-out” parameters, pass by reference to non-const

refack · 2018-09-29T02:17:20Z

P.S. Using as more standard guidelines will allow us to introduce automatic tools (MSVS and clang-tidy) to analyse, and point out non conforming code.

targos · 2018-09-29T06:57:38Z

@refack would you be for making the rule more specific? i.e. only avoid non-const references in function parameters?

refack · 2018-09-29T10:41:52Z

P.S. I forget to mention the thing that is most important to me: learning material.
All the materials I've encountered use non-const references, and explain their idiomatic meaning. (Just a quick example of something I just read 1).

IMHO it is immensely important for our code and guidance to be in line with the available learning material, to allow the inclusion of newcomers (or relearning late comers like myself)

refack · 2018-09-29T10:49:30Z

would you be for making the rule more specific? i.e. only avoid non-const references in function parameters

Yes. Something like "non const reference function argument means in/out parameter. Avoid in/out parameters" reads very clear and sound to me.

addaleax · 2018-09-29T12:21:36Z

would you be for making the rule more specific? i.e. only avoid non-const references in function parameters

Yes. Something like "non const reference function argument means in/out parameter. Avoid in/out parameters" reads very clear and sound to me.

I’m heavily -1 on that. For in/out, we should keep using pointers, since it’s otherwise completely invisible at the call site that it’s an in/out parameter.

From a personal perspective, I also agree with a few more arguments in favor of non-const reference:

They can't be uninitialized.

That’s true, yes – It’s a feature that pointers lack.

They can't be null, so they fit perfectly to the use case of a variable is not allowed to be null.

I don’t understand this – they are references, not variables themselves in the classical sense? Whatever the reference refers to could still be some kind of null/default value.

They clearly express non-ownership, while with pointers there is still doubt.

That’s fair, although we are slowly moving a lot of our C++ code to use smart pointers, which means that on the reverse side regular pointers would typically be non-owning pointers.

They provide the compiler with more optimization opportunities (unless the compiler can to prove you don't need a pointer, it will have to allocate space for it).

I doubt that, esp. the “have to allocate space for it”. Under the hood, references are pointers, and code using one type should always compile to the same assembly as code using the other type. Can you provide a reference for this claim?

IMHO they are simpler to understand. Grokking pointers requires always keeping another level of indirection in mind.

Hm – not sure I can judge this well myself, but I’m surprised by that since they are essentially the same concept, up to minor differences (no arrays using references, no default value).

@refack It’s not that I don’t understand or don’t see your points – I have used references in my C++ code a lot more before coming to the Node.js world, and had to get used to the change myself. I fully acknowledge that that took a bit of learning when writing C++ code (with a lot of other things as well, such as variable/function naming conventions etc.).

However, I’m also carrying my reviewer hat a lot of the time, and since Node.js is a mature software which millions of people use in their daily lives, I tend to value readability and more easily visible correctness higher than the ease of writing code. That’s a tradeoff, and it’s fair to stand on either side of it.

Compared this with the C++11 idiomatic (read "this is iterating using a reference because the intent is to modify").

for (auto& i : name) {
  if (i == '_') 
    i = '-';
}

Note that I’m not saying that I’m for categorically excluding these types of constructs. However, I still hold my opinion that this code obscures the fact that name is being modified, and that’s a good example of what we’re trying to avoid.

addaleax · 2018-09-30T23:26:03Z

@nodejs/tsc PTAL

CPP_STYLE_GUIDE.md

joyeecheung · 2018-10-01T12:50:27Z

CPP_STYLE_GUIDE.md

+
+ private:
+  std::string foo_string_;
+  int* pointer_to_integer_;  // Pointer instead of reference.


Personally in cases like this I'd prefer to use a normal int here and return references because it's more memory-efficient (and if this is storing a pointer to mutate it the ownership seems to be pretty hard to figure out..)...maybe a member object with a made-up class here would be clearer? Or a unique_ptr since that's what we generally try to refactor to? (Or a shared_ptr but we don't seem to use it much in our codebase and try to restructure the ownership towards a unique_ptr)

👍 … How about e9f8406?

…guide

ofrobots

LGTM.

See also additional rationale in https://google.github.io/styleguide/cppguide.html#Reference_Arguments, which is followed by V8 and Chromium.

Trott · 2018-10-02T02:26:32Z

It would seem like the reason for applying the tsc-agenda label is to request a vote to override the objection. I'm not sure if there's more to discuss here first or if it's time to have a vote. If and when vote time comes, this is outside my area of expertise so I abstain and defer to other knowledgable TSC folks.

If we're voting, here's how it looks so far:

YES:

NO:
No one yet

ABSTAIN:

UPDATE: This passes. (19 TSC members w/ 6 abstentions = 7 votes required to pass.)

thefourtheye · 2018-10-02T05:44:27Z

CPP_STYLE_GUIDE.md

+
+ private:
+  std::string foo_string_;
+  // Pointer instead of reference. If this objects 'owns' the other object,


Nit: object

@thefourtheye Thanks for catching, done!

thefourtheye · 2018-10-02T05:44:35Z

CPP_STYLE_GUIDE.md

+ private:
+  std::string foo_string_;
+  // Pointer instead of reference. If this objects 'owns' the other object,
+  // this should be be a `std::unique_ptr<OtherClass>`; a


Nit: double be

mcollina · 2018-10-02T07:18:16Z

I abstain.

MylesBorins · 2018-10-02T13:06:57Z

I abstain

… style guide

refack · 2018-10-16T00:29:55Z

@addaleax can we converge on "no non-const references as arguments in APIs"?

Avoid defining APIs with non-const reference arguments

In general, non-const references should only be used when they don't hurt readability, or if they are required by external APIs (e.g. std::for_each)

Non-const references arguments make most sense as in/out parameters [F.11]. The in/out parameter pattern is non-optimal, and should be avoided. If the parameter is a regular (in) parameter, it should be const. If in/out semantics is necessary, use a pointer as per the Google style guide.

addaleax · 2018-10-16T10:37:10Z

@refack But this isn’t just about functions/methods…

Non-const references arguments make most sense as in/out parameters [F.11]. The in/out parameter pattern is non-optimal, and should be avoided. If the parameter is a regular (in) parameter, it should be const. If in/out semantics is necessary, use a pointer as per the Google style guide.

This seems a bit confusing – why would we first mention that one thing makes sense, and then that we don’t do that because the Google style guide overrides it?

refack · 2018-10-16T13:36:53Z

But this isn’t just about functions/methods…

I'm looking for some compromise on your part...
Let's document the parts that have consensus.

addaleax · 2018-10-17T05:46:23Z

@refack I’d prefer to avoid having this exact same discussion again about the other parts, though.

Do you agree with the examples in this PR?

refack · 2018-10-17T07:28:43Z

That's why I asked for a compromise...

I don't see anything in the examples code that conflicts with the paragraph I suggested. I don't agree with the comments and the generalization that "A pointer is almost always a better choice."
AFAICT Modern C++ moves away from the classical C paradigm that "pointers are always better". And as I see it pointers and references are two equally valuable language constract that each have their own idioms, and should be used when appropriate.

addaleax · 2018-10-17T07:57:01Z

That's why I asked for a compromise...

As far as I can tell, that comment asked for documenting this in the style guide for only a subset of the use cases – That’s not really what a compromise is. (And, to mention it again: This PR documents current, existing rules.)

I don't see anything in the examples code that conflicts with the paragraph I suggested.

Yes, but your suggestion would leave the question open for a wide range of use cases (e.g. local reference variables). Those cases would otherwise be pointed out during reviews, which is less than helpful if we can also document them in our style guide for.

And as I see it pointers and references are two equally valuable language constract that each have their own idioms, and should be used when appropriate.

They both have advantages and disadvantages, so, yes, of course this depends on the use case. The big disadvantage of references, and how that can be mitigated, is mentioned here in the PR text.

If you want, I can add something like “If you use non-const references, e.g. because of an external API that uses them, consider adding a comment that indicates which objects can be modified through them.”

sam-github · 2018-10-17T15:45:03Z

@addaleax and @refack (and most of the c++ world?) agree that non-const ref args are to be avoided. @addaleax had a short paragraph elaborating why, @refack had a longer more detailed paragraph covering the same territory. More detail doesn't seem bad. I genuinely don't understand what's going on here.

"If in/out semantics is required, it is advised to use a pointer instead" and "a pointer is almost always a better choice" say the same thing, since in/out semantics is almost always why a ref arg is not const.

addaleax · 2018-10-17T19:36:29Z

@sam-github The difference here is that @refack’s text only refers to function arguments, while we currently have this as a more general rule that also applies to e.g. local variables or class members.

sam-github · 2018-10-17T20:51:22Z

Reviewed the comment thread again, and I don't see that difference in opinion. The only example Rafael showed of sane non-const refs was a for loop, which you have an example of in your code and also list as a reasonable use. If you amend your text to explicitly list the ways in which non-const refs are sometimes used, and which ones are OK (not many), and what they should be replaced with I think it would be more useful to readers of the style guide. Maybe you would disagree on some specific usage, but I don't see any specific disagreements in this thread (other than on how to express the guidance in english text).

refack · 2018-10-17T20:54:13Z

(And, to mention it again: This PR documents current, existing rules.)

Since this rule is more lore then cannon (in that it is not written down nor linted for), and since C++11 is a modernization of the language. I see this as an excellent chance to improve our rules set. Or more correctly not canonize an outdated rule.

CPP_STYLE_GUIDE.md

refack · 2018-10-17T22:28:52Z

Even V8 deviate from this rule (listing points just from the V8 public API):

node/deps/v8/include/v8.h

Lines 3398 to 3399 in c1b9be5

    
           V8_WARN_UNUSED_RESULT Maybe<bool> DefineProperty( 
        
               Local<Context> context, Local<Name> key, PropertyDescriptor& descriptor);

… in C++ style guide

addaleax · 2018-10-18T21:18:26Z

Even V8 deviate from this rule (listing points just from the V8 public API):

… which is why they explicitly mention this in the doc comment.

refack · 2018-10-18T21:56:41Z

Lite CI (Doc only change): https://ci.nodejs.org/job/node-test-pull-request-lite-pipeline/1285/

addaleax · 2018-10-21T03:04:49Z

Landed in 5550510

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>

addaleax added c++ Issues and PRs that require attention from people who are familiar with C++. doc Issues and PRs related to the documentations. tsc-agenda Issues and PRs to discuss during the meetings of the TSC. labels Sep 29, 2018

addaleax mentioned this pull request Sep 29, 2018

doc: formalize auto usage in C++ style guide #23028

Closed

3 tasks

refack suggested changes Sep 29, 2018

View reviewed changes

tniessen approved these changes Sep 29, 2018

View reviewed changes

jasnell approved these changes Oct 1, 2018

View reviewed changes

joyeecheung reviewed Oct 1, 2018

View reviewed changes

CPP_STYLE_GUIDE.md Show resolved Hide resolved

mhdawson mentioned this pull request Oct 1, 2018

Node.js Foundation Technical Steering Committee (TSC) Meeting 2018-10-03 nodejs/TSC#608

Closed

squash! doc: formalize non-const reference usage in C++ style guide

8daa18e

joyeecheung reviewed Oct 1, 2018

View reviewed changes

fixup! squash! doc: formalize non-const reference usage in C++ style …

e9f8406

…guide

targos approved these changes Oct 1, 2018

View reviewed changes

joyeecheung approved these changes Oct 1, 2018

View reviewed changes

ofrobots approved these changes Oct 1, 2018

View reviewed changes

thefourtheye reviewed Oct 2, 2018

View reviewed changes

danbev approved these changes Oct 2, 2018

View reviewed changes

fixup! fixup! squash! doc: formalize non-const reference usage in C++…

acba30d

… style guide

refack reviewed Oct 17, 2018

View reviewed changes

CPP_STYLE_GUIDE.md Show resolved Hide resolved

apapirovski approved these changes Oct 18, 2018

View reviewed changes

fixup! fixup! fixup! squash! doc: formalize non-const reference usage…

04f941a

… in C++ style guide

refack approved these changes Oct 18, 2018

View reviewed changes

refack added the author ready PRs that have at least one approval, no pending requests for changes, and a CI started. label Oct 18, 2018

addaleax removed the tsc-agenda Issues and PRs to discuss during the meetings of the TSC. label Oct 21, 2018

addaleax closed this Oct 21, 2018

addaleax deleted the cpp-style-guide-no-non-const-references branch October 21, 2018 03:04

MylesBorins added the land-on-v10.x label Nov 26, 2018

codebytere mentioned this pull request Nov 27, 2018

v10.13.1 proposal #24675

Closed

codebytere mentioned this pull request Nov 29, 2018

v10.14.2 proposal #24727

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

doc: formalize non-const reference usage in C++ style guide #23155

doc: formalize non-const reference usage in C++ style guide #23155

addaleax commented Sep 29, 2018 •

edited

Loading

nodejs-github-bot commented Sep 29, 2018

refack left a comment

refack commented Sep 29, 2018

refack commented Sep 29, 2018

targos commented Sep 29, 2018

refack commented Sep 29, 2018

refack commented Sep 29, 2018

addaleax commented Sep 29, 2018

addaleax commented Sep 30, 2018

joyeecheung Oct 1, 2018 •

edited

Loading

addaleax Oct 1, 2018

ofrobots left a comment

Trott commented Oct 2, 2018 •

edited

Loading

thefourtheye Oct 2, 2018

addaleax Oct 2, 2018

thefourtheye Oct 2, 2018

mcollina commented Oct 2, 2018

MylesBorins commented Oct 2, 2018

refack commented Oct 16, 2018 •

edited

Loading

addaleax commented Oct 16, 2018

refack commented Oct 16, 2018

addaleax commented Oct 17, 2018

refack commented Oct 17, 2018

addaleax commented Oct 17, 2018

sam-github commented Oct 17, 2018

addaleax commented Oct 17, 2018

sam-github commented Oct 17, 2018

refack commented Oct 17, 2018

refack commented Oct 17, 2018 •

edited

Loading

addaleax commented Oct 18, 2018

refack commented Oct 18, 2018

addaleax commented Oct 21, 2018

doc: formalize non-const reference usage in C++ style guide #23155

doc: formalize non-const reference usage in C++ style guide #23155

Conversation

addaleax commented Sep 29, 2018 • edited Loading

Checklist

nodejs-github-bot commented Sep 29, 2018

refack left a comment

Choose a reason for hiding this comment

refack commented Sep 29, 2018

refack commented Sep 29, 2018

targos commented Sep 29, 2018

refack commented Sep 29, 2018

refack commented Sep 29, 2018

addaleax commented Sep 29, 2018

addaleax commented Sep 30, 2018

joyeecheung Oct 1, 2018 • edited Loading

Choose a reason for hiding this comment

addaleax Oct 1, 2018

Choose a reason for hiding this comment

ofrobots left a comment

Choose a reason for hiding this comment

Trott commented Oct 2, 2018 • edited Loading

thefourtheye Oct 2, 2018

Choose a reason for hiding this comment

addaleax Oct 2, 2018

Choose a reason for hiding this comment

thefourtheye Oct 2, 2018

Choose a reason for hiding this comment

mcollina commented Oct 2, 2018

MylesBorins commented Oct 2, 2018

refack commented Oct 16, 2018 • edited Loading

Avoid defining APIs with non-const reference arguments

addaleax commented Oct 16, 2018

refack commented Oct 16, 2018

addaleax commented Oct 17, 2018

refack commented Oct 17, 2018

addaleax commented Oct 17, 2018

sam-github commented Oct 17, 2018

addaleax commented Oct 17, 2018

sam-github commented Oct 17, 2018

refack commented Oct 17, 2018

refack commented Oct 17, 2018 • edited Loading

addaleax commented Oct 18, 2018

refack commented Oct 18, 2018

addaleax commented Oct 21, 2018

addaleax commented Sep 29, 2018 •

edited

Loading

joyeecheung Oct 1, 2018 •

edited

Loading

Trott commented Oct 2, 2018 •

edited

Loading

refack commented Oct 16, 2018 •

edited

Loading

refack commented Oct 17, 2018 •

edited

Loading