From 028e38048c259da70fc62e7c684fe2a95f549de8 Mon Sep 17 00:00:00 2001 From: Joyee Cheung Date: Mon, 12 Nov 2018 07:41:19 +0800 Subject: [PATCH] doc: make C++ core guidelines a reference As our C++ codebase consists of many code that interface with third-party libraries that does not follow the C++ core guidelines, it may be difficult to enforce the guidelines without sacrificing consistency or introducing cruft that juggles with data structures. This patch makes the C++ core guidelines a reference instead of a general guideline to follow to reduce nits that are open to interpretation during code reviews, and highlights the automatic tooling for C++ styles. We may revisit the general priority when there are better automatic tools in place. --- CPP_STYLE_GUIDE.md | 25 +++++++++++++++---------- 1 file changed, 15 insertions(+), 10 deletions(-) diff --git a/CPP_STYLE_GUIDE.md b/CPP_STYLE_GUIDE.md index 5099f34ea866c9..95d33906e3f602 100644 --- a/CPP_STYLE_GUIDE.md +++ b/CPP_STYLE_GUIDE.md @@ -38,19 +38,24 @@ runtime features. Coding guidelines are based on the following guides (highest priority first): 1. This document 2. The [Google C++ Style Guide][] -3. The ISO [C++ Core Guidelines][] -In general code should follow the C++ Core Guidelines, unless overridden by the -Google C++ Style Guide or this document. At the moment these guidelines are -checked manually by reviewers, with the goal to validate this with automatic -tools. +In general code should the Google C++ Style Guide, unless overridden by this +document. -## Formatting +There are two automatic tools in this code base: + +- `make lint-cpp`: the C++ linter based on [Google’s `cpplint`][] +- `make format-cpp`: the C++ formatter based on clang-format + +At the moment guidelines that cannot be caught by these tools are checked +manually by reviewers. When nit-picking about rules that cannot be enforced +by automatic tooling during review, prefer giving specific reasons on a +case-by-case basis instead of simply citing rules. -Unfortunately, the C++ linter (based on [Google’s `cpplint`][]), which can be -run 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: +In code that does not interface with any third-party libraries, +[C++ Core Guidelines][] may be a reference for good practices. + +## Formatting ### Left-leaning (C++ style) asterisks for pointer declarations