From 43215c6c3c73d6408311364fe932678edacb21c1 Mon Sep 17 00:00:00 2001 From: Franziska Hinkelmann Date: Fri, 17 Nov 2017 11:00:31 +0100 Subject: [PATCH] doc: introduce categories to Cpp style guide Ref: https://github.com/nodejs/node/pull/17052#discussion_r151228700 PR-URL: https://github.com/nodejs/node/pull/17095 Reviewed-By: Joyee Cheung Reviewed-By: Colin Ihrig --- CPP_STYLE_GUIDE.md | 102 ++++++++++++++++++++++++--------------------- 1 file changed, 55 insertions(+), 47 deletions(-) diff --git a/CPP_STYLE_GUIDE.md b/CPP_STYLE_GUIDE.md index d3afd3c1abb7da..7f8e5a3de42e35 100644 --- a/CPP_STYLE_GUIDE.md +++ b/CPP_STYLE_GUIDE.md @@ -2,21 +2,24 @@ ## Table of Contents -* [Left-leaning (C++ style) asterisks for pointer declarations](#left-leaning-c-style-asterisks-for-pointer-declarations) -* [2 spaces of indentation for blocks or bodies of conditionals](#2-spaces-of-indentation-for-blocks-or-bodies-of-conditionals) -* [4 spaces of indentation for statement continuations](#4-spaces-of-indentation-for-statement-continuations) -* [Align function arguments vertically](#align-function-arguments-vertically) -* [Initialization lists](#initialization-lists) -* [CamelCase for methods, functions, and classes](#camelcase-for-methods-functions-and-classes) -* [snake\_case for local variables and parameters](#snake_case-for-local-variables-and-parameters) -* [snake\_case\_ for private class fields](#snake_case_-for-private-class-fields) -* [Space after `template`](#space-after-template) -* [Type casting](#type-casting) -* [Memory allocation](#memory-allocation) -* [`nullptr` instead of `NULL` or `0`](#nullptr-instead-of-null-or-0) -* [Do not include `*.h` if `*-inl.h` has already been included](#do-not-include-h-if--inlh-has-already-been-included) -* [Avoid throwing JavaScript errors in nested C++ methods](#avoid-throwing-javascript-errors-in-nested-c-methods) -* [Ownership and Smart Pointers](#ownership-and-smart-pointers) +* [Formatting](#formatting) + * [Left-leaning (C++ style) asterisks for pointer declarations](#left-leaning-c-style-asterisks-for-pointer-declarations) + * [2 spaces of indentation for blocks or bodies of conditionals](#2-spaces-of-indentation-for-blocks-or-bodies-of-conditionals) + * [4 spaces of indentation for statement continuations](#4-spaces-of-indentation-for-statement-continuations) + * [Align function arguments vertically](#align-function-arguments-vertically) + * [Initialization lists](#initialization-lists) + * [CamelCase for methods, functions and classes](#camelcase-for-methods-functions-and-classes) + * [snake\_case for local variables and parameters](#snake_case-for-local-variables-and-parameters) + * [snake\_case\_ for private class fields](#snake_case_-for-private-class-fields) + * [Space after `template`](#space-after-template) +* [Memory Management](#memory-management) + * [Memory allocation](#memory-allocation) + * [Use `nullptr` instead of `NULL` or `0`](#use-nullptr-instead-of-null-or-0) + * [Ownership and Smart Pointers](#ownership-and-smart-pointers) +* [Others](#others) + * [Type casting](#type-casting) + * [Do not include `*.h` if `*-inl.h` has already been included](#do-not-include-h-if--inlh-has-already-been-included) + * [Avoid throwing JavaScript errors in nested C++ methods](#avoid-throwing-javascript-errors-in-nested-c-methods) Unfortunately, the C++ linter (based on [Google’s `cpplint`](https://github.com/google/styleguide)), which can be run @@ -24,6 +27,8 @@ explicitly via `make lint-cpp`, does not currently catch a lot of rules that are specific to the Node.js C++ code base. This document explains the most common of these rules: +## Formatting + ## Left-leaning (C++ style) asterisks for pointer declarations `char* buffer;` instead of `char *buffer;` @@ -128,23 +133,50 @@ class FancyContainer { ... } ``` - -## Type casting - -- 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 +## Memory Management ## Memory allocation - `Malloc()`, `Calloc()`, etc. from `util.h` abort in Out-of-Memory situations - `UncheckedMalloc()`, etc. return `nullptr` in OOM situations -## `nullptr` instead of `NULL` or `0` +## Use `nullptr` instead of `NULL` or `0` What it says in the title. +## Ownership and Smart Pointers + +"Smart" pointers are classes that act like pointers, e.g. +by overloading the `*` and `->` operators. Some smart pointer types can be +used to automate ownership bookkeeping, to ensure these responsibilities are +met. `std::unique_ptr` is a smart pointer type introduced in C++11, which +expresses exclusive ownership of a dynamically allocated object; the object +is deleted when the `std::unique_ptr` goes out of scope. It cannot be +copied, but can be moved to represent ownership transfer. +`std::shared_ptr` is a smart pointer type that expresses shared ownership of a +dynamically allocated object. `std::shared_ptr`s can be copied; ownership +of the object is shared among all copies, and the object +is deleted when the last `std::shared_ptr` is destroyed. + +Prefer to use `std::unique_ptr` to make ownership +transfer explicit. For example: + +```cpp +std::unique_ptr FooFactory(); +void FooConsumer(std::unique_ptr ptr); +``` + +Never use `std::auto_ptr`. Instead, use `std::unique_ptr`. + +## Others + +## Type casting + +- 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 + ## Do not include `*.h` if `*-inl.h` has already been included Do @@ -169,27 +201,3 @@ A lot of code inside Node.js is written so that typechecking etc. is performed in JavaScript. Using C++ `throw` is not allowed. - -## Ownership and Smart Pointers - -"Smart" pointers are classes that act like pointers, e.g. -by overloading the `*` and `->` operators. Some smart pointer types can be -used to automate ownership bookkeeping, to ensure these responsibilities are -met. `std::unique_ptr` is a smart pointer type introduced in C++11, which -expresses exclusive ownership of a dynamically allocated object; the object -is deleted when the `std::unique_ptr` goes out of scope. It cannot be -copied, but can be moved to represent ownership transfer. -`std::shared_ptr` is a smart pointer type that expresses shared ownership of a -dynamically allocated object. `std::shared_ptr`s can be copied; ownership -of the object is shared among all copies, and the object -is deleted when the last `std::shared_ptr` is destroyed. - -Prefer to use `std::unique_ptr` to make ownership -transfer explicit. For example: - -```cpp -std::unique_ptr FooFactory(); -void FooConsumer(std::unique_ptr ptr); -``` - -Never use `std::auto_ptr`. Instead, use `std::unique_ptr`.