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 <joyeec9h3@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>

1 files changed, 55 insertions, 47 deletions

diff --git a/CPP_STYLE_GUIDE.md b/CPP_STYLE_GUIDE.md
index d3afd3c1ab..7f8e5a3de4 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<Foo> FooFactory();
+void FooConsumer(std::unique_ptr<Foo> 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<Foo> FooFactory();
-void FooConsumer(std::unique_ptr<Foo> ptr);
-```
-
-Never use `std::auto_ptr`. Instead, use `std::unique_ptr`.