doc: add basic C++ style guide #16090

addaleax · 2017-10-08T19:31:15Z

Ideally, most of these things would be enforced via linter rules. This is a first step into having a style guide that goes beyond what the linter currently enforces.

This is probably relevant to most of: @bnoordhuis @jasnell @TimothyGu @trevnorris @danbev @eugeneo @nodejs/n-api

bnoordhuis

LGTM with two suggestions. Good idea and nice work, Anna!

bnoordhuis · 2017-10-08T19:45:00Z

CPP_STYLE_GUIDE.md

+class FooBar {
+ public:
+  void DoSomething();
+  static void DoSomethingButItsStaticInstead();


We also use foo() and set_foo() for simple getters/setters (with const-correctness whenever possible.)

bnoordhuis · 2017-10-08T19:45:49Z

CPP_STYLE_GUIDE.md

+
+What it says in the title.
+
+## Avoid throwing errors in nested C++ methods


Suggestion: s/errors/JavaScript errors/ - this section could be interpreted to mean that throw is allowed.

refack

Yay 👏

refack · 2017-10-08T19:52:06Z

CPP_STYLE_GUIDE.md

@@ -0,0 +1,111 @@
+# C++ style guide
+
+Unfortunately, the C++ linter (which can be run explicitly


IMHO Google's style guide is still a good reference.

...the C++ linter (based on [Google's `cpplint`](https://github.com/google/styleguide), and which can...

refack · 2017-10-08T19:55:22Z

CPP_STYLE_GUIDE.md

+    ...);
+```
+
+## CamelCase for methods, functions and classes


When I grew up this was called PascalCase, and camel case is what's now known as lowerCamelCase

I’ve never heard of that term, and in any case the example’s very purpose is to avoid any ambiguity about what is meant.

👍 Cool. Examples beat all.

jasnell

Awesome!

TimothyGu · 2017-10-08T21:19:42Z

CPP_STYLE_GUIDE.md

+};
+```
+
+## snake_case for local variables and parameters


Please escape the underscores for non-GitHub markdown readers.

thanks, done!

TimothyGu · 2017-10-08T21:32:16Z

CPP_STYLE_GUIDE.md

+If you need to throw JavaScript errors from a C++ binding method, try to do it
+at the top level and not inside of nested calls.
+
+(Using C++ `throw` is not allowed.)


This sentence sounds odd being positioned here, sandwiched between two sentences talking about JavaScript errors.

I’ve moved it to the end. I added it because it seemed to make sense to me that, like @bnoordhuis said, there might be confusion about what “throwing” means, but I’d also be happy just dropping it

TimothyGu · 2017-10-08T21:34:33Z

cc @BridgeAR

TimothyGu

There's also:

namespace does not increase indentation level
Wrap at 80 cols
Use references (char&) only if it's constant (const char&); otherwise use pointers (char*)

addaleax · 2017-10-08T21:40:30Z

@TimothyGu This was specifically about things that the linter doesn’t complain about, I’m pretty sure it does for all of these things

TimothyGu · 2017-10-08T21:45:43Z

@addaleax It doesn't always report the first one (see ade80ee). The rest, yes, I believe cpplint does report them all.

danbev · 2017-10-09T05:26:01Z

CPP_STYLE_GUIDE.md

-rules:
+Unfortunately, the C++ linter (based on
+[Google’s `cpplint`](https://github.com/google/styleguide)), which can be run
+explicitly via `make cpplint`, does not currently catch a lot of rules that are


Should this perhaps be make lint-cpp instead? Running make cppilnt target produces the following warning:

$ make cpplint Running C++ linter... Total errors found: 0 Please use lint-cpp instead of cpplint

@danbev yes, I guess so :)

Fishrock123

FunctionWithAReallyReallyReallyLongNameSeriouslyStopIt 😂

Mind to punctuate the lists?

Aside form the memory section comment though this is very helpful!

Should this doc be top-level, or live inside doc/? I suppose we may want it visible and then just get rid of it once we get some sort of new linting in place?

Fishrock123 · 2017-10-09T17:55:40Z

CPP_STYLE_GUIDE.md

+- Use `static_cast` for casting whenever it works
+- `reinterpret_cast` is okay if `static_cast` is not appropriate
+
+## Memory allocation


Could these two be clarified... slightly?

Do you have any specific question? I realize this isn’t helpful when it comes to which-do-I-use, but then again we don’t really follow any specific rules for this right now. (I assume @bnoordhuis is a fan of just aborting in OOM situations, me not so much. 😄)

Oh, ok. On re-reading it I think I understand, maybe we could clarify the wording like so:

- Use `Malloc()`, `Calloc()`, etc. from `util.h` to cause an abort in Out-of-Memory situations. - Use `UncheckedMalloc()`, etc. to return a `nullptr` in OOM situations.

gibfahn · 2017-10-09T18:13:54Z

Should this doc be top-level, or live inside doc/? I suppose we may want it visible and then just get rid of it once we get some sort of new linting in place?

My first thought would be to put it in doc with the other STYLE_GUIDE.

It might be worth including a reference to it in PULL_REQUEST_TEMPLATE.md too, but on the other hand that template is already quite long already, and lots of people don't read it (and it wouldn't apply to most PRs).

trevnorris

Doc looks great.

Left a few notes, but nothing blocking.

trevnorris · 2017-10-09T22:04:10Z

CPP_STYLE_GUIDE.md

+ ...
+}
+```
+


another common pattern is how we handle indentation of initialization lists. example:

HandleWrap::HandleWrap(Environment* env, Local<Object> object, uv_handle_t* handle, AsyncWrap::ProviderType provider) : AsyncWrap(env, object, provider), state_(kInitialized), handle_(handle) {

basically: if the initialization list does not fit on one line then it returns to the next line, indents 4 spaces then starts with the colon. Every additional member in the list starts on a new line and indented 6 spaced, to align with the first member in the list.

trevnorris · 2017-10-09T22:06:59Z

CPP_STYLE_GUIDE.md

+- Always avoid C-style casts (`(type)value`)
+- `dynamic_cast` does not work because RTTI is not enabled
+- Use `static_cast` for casting whenever it works
+- `reinterpret_cast` is okay if `static_cast` is not appropriate


it may be worth mentioning usage of const_cast (since it's used in core) but not sure if there's a solid rule of when it's acceptable.

const_cast: should be used sparingly and only when it's still conceptually const afterwards.

there is nothing specific to Node about using const_cast, anything we’d write down here would apply to any other C++ code as well

trevnorris · 2017-10-09T22:14:25Z

CPP_STYLE_GUIDE.md

+
+```c++
+VeryLongTypeName very_long_result = SomeValueWithAVeryLongName +
+    SomeOtherValueWithAVeryLongName;


the linter doesn't currently catch whether the operation is at the end of the line or the beginning of the next line. couple examples:

// ternary int r = true ? 1 : 0; int r = true ? 1 : 0; // conditional if (foo && bar) { } if (foo && bar) { }

specify this?

@addaleax /cc @bnoordhuis

The && should go on the same line as the expression preceding it. (edit: but I believe the linter already complains about that.)

Ternary operator: we don't have a hard rule, I think, but IMO if it doesn't fit on a single line, you should be using an if statement anyway.

re: placement of &&. linter doesn't check that. should be possible to add to the linter? if so then no reason to put it here.

addaleax · 2017-10-10T13:19:21Z

@TimothyGu

namespace does not increase indentation level

I’ve added a sentence for this.

@gibfahn

My first thought would be to put it in doc with the other STYLE_GUIDE.

That’s in doc/ because it’s a style guide for documentation, though.

gibfahn · 2017-10-10T23:20:28Z

That’s in doc/ because it’s a style guide for documentation, though.

Then maybe in src/? Should show up at the top in there. I think that the top level directory is pretty cluttered as it is, and I wonder if putting it in a sub-directory might make it more discoverable. I've been told by a few people that the top level directory has too much, and it's difficult to find anything.

Non-blocking though, feel free to ignore if you disagree.

cjihrig · 2017-10-11T00:58:58Z

CPP_STYLE_GUIDE.md

+}
+```
+
+(Braces are optional if the statement body only has one line.)


The parens can probably be dropped here.

cjihrig · 2017-10-11T01:04:07Z

CPP_STYLE_GUIDE.md

+A lot of code inside Node.js is written so that typechecking etc. is performed
+in JavaScript.
+
+(Using C++ `throw` is not allowed.)


Parens could be dropped here as well.

mhdawson

LGTM, great to have this guidance written down,

Ideally, most of these things would be enforced via linter rules. This is a first step into having a style guide that goes beyond what the linter currently enforces.

addaleax · 2017-10-12T00:33:49Z

@gibfahn I’m still a bit worried that that would make this a lot less easily discoverable…

refack · 2017-10-12T17:31:19Z

Landing this PR will resolve #12636

tniessen · 2017-10-12T22:55:12Z

CPP_STYLE_GUIDE.md

@@ -0,0 +1,138 @@
+# C++ style guide


This is capitalized in CONTRIBUTING.md, I'd suggest to do the same here.

tniessen · 2017-10-12T22:56:49Z

CPP_STYLE_GUIDE.md

+
+## Left-leaning (C++ style) asterisks for pointer declarations
+
+`char* buffer;` instead of `char *buffer;`


No doubt this is correct, but it always bothers me with multiple variables:

void* foo, * bar;

I'd just declare one variable per line

tniessen · 2017-10-12T22:59:41Z

CPP_STYLE_GUIDE.md

+
+`char* buffer;` instead of `char *buffer;`
+
+## 2 spaces of indentation for blocks or bodies of conditionals


Also for loops (unless conditionals includes loops).

while (something) ChangeSomething();

Now that I am thinking about it, I am not sure we use loops without parens...

Yeah, conditionals includes conditional loops. :) Anyway, I don’t think the current phrasing leaves anybody thinking that we use indentation other than 2 spaces.

addaleax · 2017-10-14T09:13:56Z

Landed in 23340b9

Ideally, most of these things would be enforced via linter rules. This is a first step into having a style guide that goes beyond what the linter currently enforces. PR-URL: #16090 Fixes: #12636 Reviewed-By: Refael Ackermann <refack@gmail.com> Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl> Reviewed-By: Daniel Bevenius <daniel.bevenius@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Timothy Gu <timothygu99@gmail.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Tobias Nießen <tniessen@tnie.de> Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>

Ideally, most of these things would be enforced via linter rules. This is a first step into having a style guide that goes beyond what the linter currently enforces. PR-URL: nodejs/node#16090 Fixes: nodejs/node#12636 Reviewed-By: Refael Ackermann <refack@gmail.com> Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl> Reviewed-By: Daniel Bevenius <daniel.bevenius@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Timothy Gu <timothygu99@gmail.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Tobias Nießen <tniessen@tnie.de> Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>

Ideally, most of these things would be enforced via linter rules. This is a first step into having a style guide that goes beyond what the linter currently enforces. PR-URL: #16090 Fixes: #12636 Reviewed-By: Refael Ackermann <refack@gmail.com> Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl> Reviewed-By: Daniel Bevenius <daniel.bevenius@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Timothy Gu <timothygu99@gmail.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Tobias Nießen <tniessen@tnie.de> Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>

MylesBorins · 2017-11-16T19:40:37Z

This does not land cleanly in LTS. Please feel free to manually backport by following the guide. Please also feel free to replace do-not-land if it is being backported

nodejs-github-bot added the doc Issues and PRs related to the documentations. label Oct 8, 2017

addaleax added the c++ Issues and PRs that require attention from people who are familiar with C++. label Oct 8, 2017

bnoordhuis approved these changes Oct 8, 2017

View reviewed changes

refack approved these changes Oct 8, 2017

View reviewed changes

jasnell approved these changes Oct 8, 2017

View reviewed changes

TimothyGu reviewed Oct 8, 2017

View reviewed changes

addaleax force-pushed the cpp-style-guide branch from f76063e to 78d870e Compare October 8, 2017 21:35

TimothyGu approved these changes Oct 8, 2017

View reviewed changes

danbev approved these changes Oct 9, 2017

View reviewed changes

danbev reviewed Oct 9, 2017

View reviewed changes

Fishrock123 reviewed Oct 9, 2017

View reviewed changes

trevnorris reviewed Oct 9, 2017

View reviewed changes

joyeecheung mentioned this pull request Oct 10, 2017

[WIP] tools: use clang-format to format C++ code #16122

Closed

2 tasks

TimothyGu approved these changes Oct 10, 2017

View reviewed changes

cjihrig approved these changes Oct 11, 2017

View reviewed changes

mhdawson approved these changes Oct 11, 2017

View reviewed changes

addaleax added 4 commits October 12, 2017 02:33

doc: add basic C++ style guide

a4417a5

Ideally, most of these things would be enforced via linter rules. This is a first step into having a style guide that goes beyond what the linter currently enforces.

address nits

39ab867

address more nits

b6a028c

more nits

66a546d

[squash] cjihrig nits

68176fe

addaleax force-pushed the cpp-style-guide branch from 5ca7f32 to 68176fe Compare October 12, 2017 00:34

refack mentioned this pull request Oct 12, 2017

doc: link to code style guide #12636

Closed

tniessen approved these changes Oct 12, 2017

View reviewed changes

[squash] capitalize Style Guide

8b289f1

addaleax closed this Oct 14, 2017

addaleax deleted the cpp-style-guide branch October 14, 2017 09:14

MylesBorins added the dont-land-on-v6.x label Nov 16, 2017

MarcelRaschke mentioned this pull request Aug 19, 2022

[Snyk] Upgrade eslint from 7.32.0 to 8.20.0 MarcelRaschke/node#6

Open


		What it says in the title.

		## Avoid throwing errors in nested C++ methods

		@@ -0,0 +1,111 @@
		# C++ style guide

		Unfortunately, the C++ linter (which can be run explicitly


		## Left-leaning (C++ style) asterisks for pointer declarations

		`char* buffer;` instead of `char *buffer;`


		`char* buffer;` instead of `char *buffer;`

		## 2 spaces of indentation for blocks or bodies of conditionals

doc: add basic C++ style guide #16090

doc: add basic C++ style guide #16090

Conversation

addaleax commented Oct 8, 2017

bnoordhuis left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

refack left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jasnell left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

TimothyGu commented Oct 8, 2017

TimothyGu left a comment

Choose a reason for hiding this comment

addaleax commented Oct 8, 2017

TimothyGu commented Oct 8, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Fishrock123 left a comment • edited Loading

Choose a reason for hiding this comment

Fishrock123 Oct 9, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gibfahn commented Oct 9, 2017

trevnorris left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bnoordhuis Oct 10, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

addaleax commented Oct 10, 2017

gibfahn commented Oct 10, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mhdawson left a comment

Choose a reason for hiding this comment

addaleax commented Oct 12, 2017

refack commented Oct 12, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

addaleax commented Oct 14, 2017

MylesBorins commented Nov 16, 2017

Fishrock123 left a comment •

edited

Loading

Fishrock123 Oct 9, 2017 •

edited

Loading

bnoordhuis Oct 10, 2017 •

edited

Loading