|
207
|
1 <!--===- docs/C++style.md
|
|
|
2
|
|
|
3 Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
|
|
|
4 See https://llvm.org/LICENSE.txt for license information.
|
|
|
5 SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
|
|
|
6
|
|
|
7 -->
|
|
|
8
|
|
|
9 # Flang C++ Style Guide
|
|
|
10
|
|
|
11 ```eval_rst
|
|
|
12 .. contents::
|
|
|
13 :local:
|
|
|
14 ```
|
|
|
15
|
|
|
16 This document captures the style guide rules that are followed in the Flang codebase.
|
|
|
17
|
|
|
18 ## In brief:
|
|
|
19 * Use *clang-format*
|
|
|
20 from llvm 7
|
|
|
21 on all C++ source and header files before
|
|
|
22 every merge to master. All code layout should be determined
|
|
|
23 by means of clang-format.
|
|
|
24 * Where a clear precedent exists in the project, follow it.
|
|
|
25 * Otherwise, where [LLVM's C++ style guide](https://llvm.org/docs/CodingStandards.html#style-issues)
|
|
|
26 is clear on usage, follow it.
|
|
|
27 * Otherwise, where a good public C++ style guide is relevant and clear,
|
|
|
28 follow it. [Google's](https://google.github.io/styleguide/cppguide.html)
|
|
|
29 is pretty good and comes with lots of justifications for its rules.
|
|
|
30 * Reasonable exceptions to these guidelines can be made.
|
|
|
31 * Be aware of some workarounds for known issues in older C++ compilers that should
|
|
|
32 still be able to compile f18. They are listed at the end of this document.
|
|
|
33
|
|
|
34 ## In particular:
|
|
|
35
|
|
|
36 Use serial commas in comments, error messages, and documentation
|
|
|
37 unless they introduce ambiguity.
|
|
|
38
|
|
|
39 ### Error messages
|
|
|
40 1. Messages should be a single sentence with few exceptions.
|
|
|
41 1. Fortran keywords should appear in upper case.
|
|
|
42 1. Names from the program appear in single quotes.
|
|
|
43 1. Messages should start with a capital letter.
|
|
|
44 1. Messages should not end with a period.
|
|
|
45
|
|
|
46 ### Files
|
|
|
47 1. File names should use dashes, not underscores. C++ sources have the
|
|
|
48 extension ".cpp", not ".C" or ".cc" or ".cxx". Don't create needless
|
|
|
49 source directory hierarchies.
|
|
|
50 1. Header files should be idempotent. Use the usual technique:
|
|
|
51 ```
|
|
|
52 #ifndef FORTRAN_header_H_
|
|
|
53 #define FORTRAN_header_H_
|
|
|
54 // code
|
|
|
55 #endif // FORTRAN_header_H_
|
|
|
56 ```
|
|
|
57 1. `#include` every header defining an entity that your project header or source
|
|
|
58 file actually uses directly. (Exception: when foo.cpp starts, as it should,
|
|
|
59 with `#include "foo.h"`, and foo.h includes bar.h in order to define the
|
|
|
60 interface to the module foo, you don't have to redundantly `#include "bar.h"`
|
|
|
61 in foo.cpp.)
|
|
|
62 1. In the source file "foo.cpp", put its corresponding `#include "foo.h"`
|
|
|
63 first in the sequence of inclusions.
|
|
|
64 Then `#include` other project headers in alphabetic order; then C++ standard
|
|
|
65 headers, also alphabetically; then C and system headers.
|
|
|
66 1. Don't use `#include <iostream>`. If you need it for temporary debugging,
|
|
|
67 remove the inclusion before committing.
|
|
|
68
|
|
|
69 ### Naming
|
|
|
70 1. C++ names that correspond to well-known interfaces from the STL, LLVM,
|
|
|
71 and Fortran standard
|
|
|
72 can and should look like their models when the reader can safely assume that
|
|
|
73 they mean the same thing -- e.g., `clear()` and `size()` member functions
|
|
|
74 in a class that implements an STL-ish container.
|
|
|
75 Fortran intrinsic function names are conventionally in ALL CAPS.
|
|
|
76 1. Non-public data members should be named with leading miniscule (lower-case)
|
|
|
77 letters, internal camelCase capitalization, and a trailing underscore,
|
|
|
78 e.g. `DoubleEntryBookkeepingSystem myLedger_;`. POD structures with
|
|
|
79 only public data members shouldn't use trailing underscores, since they
|
|
|
80 don't have class functions from which data members need to be distinguishable.
|
|
|
81 1. Accessor member functions are named with the non-public data member's name,
|
|
|
82 less the trailing underscore. Mutator member functions are named `set_...`
|
|
|
83 and should return `*this`. Don't define accessors or mutators needlessly.
|
|
|
84 1. Other class functions should be named with leading capital letters,
|
|
|
85 CamelCase, and no underscores, and, like all functions, should be based
|
|
|
86 on imperative verbs, e.g. `HaltAndCatchFire()`.
|
|
|
87 1. It is fine to use short names for local variables with limited scopes,
|
|
|
88 especially when you can declare them directly in a `for()`/`while()`/`if()`
|
|
|
89 condition. Otherwise, prefer complete English words to abbreviations
|
|
|
90 when creating names.
|
|
|
91
|
|
|
92 ### Commentary
|
|
|
93 1. Use `//` for all comments except for short `/*notes*/` within expressions.
|
|
|
94 1. When `//` follows code on a line, precede it with two spaces.
|
|
|
95 1. Comments should matter. Assume that the reader knows current C++ at least as
|
|
|
96 well as you do and avoid distracting her by calling out usage of new
|
|
|
97 features in comments.
|
|
|
98
|
|
|
99 ### Layout
|
|
|
100 Always run `clang-format` on your changes before committing code. LLVM
|
|
|
101 has a `git-clang-format` script to facilitate running clang-format only
|
|
|
102 on the lines that have changed.
|
|
|
103
|
|
|
104 Here's what you can expect to see `clang-format` do:
|
|
|
105 1. Indent with two spaces.
|
|
|
106 1. Don't indent public:, protected:, and private:
|
|
|
107 accessibility labels.
|
|
|
108 1. Never use more than 80 characters per source line.
|
|
|
109 1. Don't use tabs.
|
|
|
110 1. Don't indent the bodies of namespaces, even when nested.
|
|
|
111 1. Function result types go on the same line as the function and argument
|
|
|
112 names.
|
|
|
113
|
|
|
114 Don't try to make columns of variable names or comments
|
|
|
115 align vertically -- they are maintenance problems.
|
|
|
116
|
|
|
117 Always wrap the bodies of `if()`, `else`, `while()`, `for()`, `do`, &c.
|
|
|
118 with braces, even when the body is a single statement or empty. The
|
|
|
119 opening `{` goes on
|
|
|
120 the end of the line, not on the next line. Functions also put the opening
|
|
|
121 `{` after the formal arguments or new-style result type, not on the next
|
|
|
122 line. Use `{}` for empty inline constructors and destructors in classes.
|
|
|
123
|
|
|
124 If any branch of an `if`/`else if`/`else` cascade ends with a return statement,
|
|
|
125 they all should, with the understanding that the cases are all unexceptional.
|
|
|
126 When testing for an error case that should cause an early return, do so with
|
|
|
127 an `if` that doesn't have a following `else`.
|
|
|
128
|
|
|
129 Don't waste space on the screen with needless blank lines or elaborate block
|
|
|
130 commentary (lines of dashes, boxes of asterisks, &c.). Write code so as to be
|
|
|
131 easily read and understood with a minimum of scrolling.
|
|
|
132
|
|
|
133 Avoid using assignments in controlling expressions of `if()` &c., even with
|
|
|
134 the idiom of wrapping them with extra parentheses.
|
|
|
135
|
|
|
136 In multi-element initializer lists (especially `common::visitors{...}`),
|
|
|
137 including a comma after the last element often causes `clang-format` to do
|
|
|
138 a better jobs of formatting.
|
|
|
139
|
|
|
140 ### C++ language
|
|
|
141 Use *C++17*, unless some compiler to which we must be portable lacks a feature
|
|
|
142 you are considering.
|
|
|
143 However:
|
|
|
144 1. Never throw or catch exceptions.
|
|
|
145 1. Never use run-time type information or `dynamic_cast<>`.
|
|
|
146 1. Never declare static data that executes a constructor.
|
|
|
147 (This is why `#include <iostream>` is contraindicated.)
|
|
|
148 1. Use `{braced initializers}` in all circumstances where they work, including
|
|
|
149 default data member initialization. They inhibit implicit truncation.
|
|
|
150 Don't use `= expr` initialization just to effect implicit truncation;
|
|
|
151 prefer an explicit `static_cast<>`.
|
|
|
152 With C++17, braced initializers work fine with `auto` too.
|
|
|
153 Sometimes, however, there are better alternatives to empty braces;
|
|
|
154 e.g., prefer `return std::nullopt;` to `return {};` to make it more clear
|
|
|
155 that the function's result type is a `std::optional<>`.
|
|
|
156 1. Avoid unsigned types apart from `size_t`, which must be used with care.
|
|
|
157 When `int` just obviously works, just use `int`. When you need something
|
|
|
158 bigger than `int`, use `std::int64_t` rather than `long` or `long long`.
|
|
|
159 1. Use namespaces to avoid conflicts with client code. Use one top-level
|
|
|
160 `Fortran` project namespace. Don't introduce needless nested namespaces within the
|
|
|
161 project when names don't conflict or better solutions exist. Never use
|
|
|
162 `using namespace ...;` outside test code; never use `using namespace std;`
|
|
|
163 anywhere. Access STL entities with names like `std::unique_ptr<>`,
|
|
|
164 without a leading `::`.
|
|
|
165 1. Prefer `static` functions over functions in anonymous namespaces in source files.
|
|
|
166 1. Use `auto` judiciously. When the type of a local variable is known,
|
|
|
167 monomorphic, and easy to type, be explicit rather than using `auto`.
|
|
|
168 Don't use `auto` functions unless the type of the result of an outlined member
|
|
|
169 function definition can be more clear due to its use of types declared in the
|
|
|
170 class.
|
|
|
171 1. Use move semantics and smart pointers to make dynamic memory ownership
|
|
|
172 clear. Consider reworking any code that uses `malloc()` or a (non-placement)
|
|
|
173 `operator new`.
|
|
|
174 See the section on Pointers below for some suggested options.
|
|
|
175 1. When defining argument types, use values when object semantics are
|
|
|
176 not required and the value is small and copyable without allocation
|
|
|
177 (e.g., `int`);
|
|
|
178 use `const` or rvalue references for larger values (e.g., `std::string`);
|
|
|
179 use `const` references to rather than pointers to immutable objects;
|
|
|
180 and use non-`const` references for mutable objects, including "output" arguments
|
|
|
181 when they can't be function results.
|
|
|
182 Put such output arguments last (_pace_ the standard C library conventions for `memcpy()` & al.).
|
|
|
183 1. Prefer `typename` to `class` in template argument declarations.
|
|
|
184 1. Prefer `enum class` to plain `enum` wherever `enum class` will work.
|
|
|
185 We have an `ENUM_CLASS` macro that helps capture the names of constants.
|
|
|
186 1. Use `constexpr` and `const` generously.
|
|
|
187 1. When a `switch()` statement's labels do not cover all possible case values
|
|
|
188 explicitly, it should contain either a `default:;` at its end or a
|
|
|
189 `default:` label that obviously crashes; we have a `CRASH_NO_CASE` macro
|
|
|
190 for such situations.
|
|
|
191 1. On the other hand, when a `switch()` statement really does cover all of
|
|
|
192 the values of an `enum class`, please insert a call to the `SWITCH_COVERS_ALL_CASES`
|
|
|
193 macro at the top of the block. This macro does the right thing for G++ and
|
|
|
194 clang to ensure that no warning is emitted when the cases are indeed all covered.
|
|
|
195 1. When using `std::optional` values, avoid unprotected access to their content.
|
|
|
196 This is usually by means of `x.has_value()` guarding execution of `*x`.
|
|
|
197 This is implicit when they are function results assigned to local variables
|
|
|
198 in `if`/`while` predicates.
|
|
|
199 When no presence test is obviously protecting a `*x` reference to the
|
|
|
200 contents, and it is assumed that the contents are present, validate that
|
|
|
201 assumption by using `x.value()` instead.
|
|
|
202 1. We use `c_str()` rather than `data()` when converting a `std::string`
|
|
|
203 to a `const char *` when the result is expected to be NUL-terminated.
|
|
|
204 1. Avoid explicit comparisions of pointers to `nullptr` and tests of
|
|
|
205 presence of `optional<>` values with `.has_value()` in the predicate
|
|
|
206 expressions of control flow statements, but prefer them to implicit
|
|
|
207 conversions to `bool` when initializing `bool` variables and arguments,
|
|
|
208 and to the use of the idiom `!!`.
|
|
|
209
|
|
|
210 #### Classes
|
|
|
211 1. Define POD structures with `struct`.
|
|
|
212 1. Don't use `this->` in (non-static) member functions, unless forced to
|
|
|
213 do so in a template member function.
|
|
|
214 1. Define accessor and mutator member functions (implicitly) inline in the
|
|
|
215 class, after constructors and assignments. Don't needlessly define
|
|
|
216 (implicit) inline member functions in classes unless they really solve a
|
|
|
217 performance problem.
|
|
|
218 1. Try to make class definitions in headers concise specifications of
|
|
|
219 interfaces, at least to the extent that C++ allows.
|
|
|
220 1. When copy constructors and copy assignment are not necessary,
|
|
|
221 and move constructors/assignment is present, don't declare them and they
|
|
|
222 will be implicitly deleted. When neither copy nor move constructors
|
|
|
223 or assignments should exist for a class, explicitly `=delete` all of them.
|
|
|
224 1. Make single-argument constructors (other than copy and move constructors)
|
|
|
225 'explicit' unless you really want to define an implicit conversion.
|
|
|
226
|
|
|
227 #### Pointers
|
|
|
228 There are many -- perhaps too many -- means of indirect addressing
|
|
|
229 data in this project.
|
|
|
230 Some of these are standard C++ language and library features,
|
|
|
231 while others are local inventions in `lib/Common`:
|
|
|
232 * Bare pointers (`Foo *p`): these are obviously nullable, non-owning,
|
|
|
233 undefined when uninitialized, shallowly copyable, reassignable, and often
|
|
|
234 not the right abstraction to use in this project.
|
|
|
235 But they can be the right choice to represent an optional
|
|
|
236 non-owning reference, as in a function result.
|
|
|
237 Use the `DEREF()` macro to convert a pointer to a reference that isn't
|
|
|
238 already protected by an explicit test for null.
|
|
|
239 * References (`Foo &r`, `const Foo &r`): non-nullable, not owning,
|
|
|
240 shallowly copyable, and not reassignable.
|
|
|
241 References are great for invisible indirection to objects whose lifetimes are
|
|
|
242 broader than that of the reference.
|
|
|
243 Take care when initializing a reference with another reference to ensure
|
|
|
244 that a copy is not made because only one of the references is `const`;
|
|
|
245 this is a pernicious C++ language pitfall!
|
|
|
246 * Rvalue references (`Foo &&r`): These are non-nullable references
|
|
|
247 *with* ownership, and they are ubiquitously used for formal arguments
|
|
|
248 wherever appropriate.
|
|
|
249 * `std::reference_wrapper<>`: non-nullable, not owning, shallowly
|
|
|
250 copyable, and (unlike bare references) reassignable, so suitable for
|
|
|
251 use in STL containers and for data members in classes that need to be
|
|
|
252 copyable or assignable.
|
|
|
253 * `common::Reference<>`: like `std::reference_wrapper<>`, but also supports
|
|
|
254 move semantics, member access, and comparison for equality; suitable for use in
|
|
|
255 `std::variant<>`.
|
|
|
256 * `std::unique_ptr<>`: A nullable pointer with ownership, null by default,
|
|
|
257 not copyable, reassignable.
|
|
|
258 F18 has a helpful `Deleter<>` class template that makes `unique_ptr<>`
|
|
|
259 easier to use with forward-referenced data types.
|
|
|
260 * `std::shared_ptr<>`: A nullable pointer with shared ownership via reference
|
|
|
261 counting, null by default, shallowly copyable, reassignable, and slow.
|
|
|
262 * `Indirection<>`: A non-nullable pointer with ownership and
|
|
|
263 optional deep copy semantics; reassignable.
|
|
|
264 Often better than a reference (due to ownership) or `std::unique_ptr<>`
|
|
|
265 (due to non-nullability and copyability).
|
|
|
266 Can be wrapped in `std::optional<>` when nullability is required.
|
|
|
267 Usable with forward-referenced data types with some use of `extern template`
|
|
|
268 in headers and explicit template instantiation in source files.
|
|
|
269 * `CountedReference<>`: A nullable pointer with shared ownership via
|
|
|
270 reference counting, null by default, shallowly copyable, reassignable.
|
|
|
271 Safe to use *only* when the data are private to just one
|
|
|
272 thread of execution.
|
|
|
273 Used sparingly in place of `std::shared_ptr<>` only when the overhead
|
|
|
274 of that standard feature is prohibitive.
|
|
|
275
|
|
|
276 A feature matrix:
|
|
|
277
|
|
|
278 | indirection | nullable | default null | owning | reassignable | copyable | undefined type ok? |
|
|
|
279 | ----------- | -------- | ------------ | ------ | ------------ | -------- | ------------------ |
|
|
|
280 | `*p` | yes | no | no | yes | shallowly | yes |
|
|
|
281 | `&r` | no | n/a | no | no | shallowly | yes |
|
|
|
282 | `&&r` | no | n/a | yes | no | shallowly | yes |
|
|
|
283 | `reference_wrapper<>` | no | n/a | no | yes | shallowly | yes |
|
|
|
284 | `Reference<>` | no | n/a | no | yes | shallowly | yes |
|
|
|
285 | `unique_ptr<>` | yes | yes | yes | yes | no | yes, with work |
|
|
|
286 | `shared_ptr<>` | yes | yes | yes | yes | shallowly | no |
|
|
|
287 | `Indirection<>` | no | n/a | yes | yes | optionally deeply | yes, with work |
|
|
|
288 | `CountedReference<>` | yes | yes | yes | yes | shallowly | no |
|
|
|
289
|
|
|
290 ### Overall design preferences
|
|
|
291 Don't use dynamic solutions to solve problems that can be solved at
|
|
|
292 build time; don't solve build time problems by writing programs that
|
|
|
293 produce source code when macros and templates suffice; don't write macros
|
|
|
294 when templates suffice. Templates are statically typed, checked by the
|
|
|
295 compiler, and are (or should be) visible to debuggers.
|
|
|
296
|
|
|
297 ### Exceptions to these guidelines
|
|
|
298 Reasonable exceptions will be allowed; these guidelines cannot anticipate
|
|
|
299 all situations.
|
|
|
300 For example, names that come from other sources might be more clear if
|
|
|
301 their original spellings are preserved rather than mangled to conform
|
|
|
302 needlessly to the conventions here, as Google's C++ style guide does
|
|
|
303 in a way that leads to weirdly capitalized abbreviations in names
|
|
|
304 like `Http`.
|
|
|
305 Consistency is one of many aspects in the pursuit of clarity,
|
|
|
306 but not an end in itself.
|
|
|
307
|
|
|
308 ## C++ compiler bug workarounds
|
|
|
309 Below is a list of workarounds for C++ compiler bugs met with f18 that, even
|
|
|
310 if the bugs are fixed in latest C++ compiler versions, need to be applied so
|
|
|
311 that all desired tool-chains can compile f18.
|
|
|
312
|
|
|
313 ### Explicitly move noncopyable local variable into optional results
|
|
|
314
|
|
|
315 The following code is legal C++ but fails to compile with the
|
|
|
316 default Ubuntu 18.04 g++ compiler (7.4.0-1ubuntu1~18.0.4.1):
|
|
|
317
|
|
|
318 ```
|
|
|
319 class CantBeCopied {
|
|
|
320 public:
|
|
|
321 CantBeCopied(const CantBeCopied&) = delete;
|
|
|
322 CantBeCopied(CantBeCopied&&) = default;
|
|
|
323 CantBeCopied() {}
|
|
|
324 };
|
|
|
325 std::optional<CantBeCopied> fooNOK() {
|
|
|
326 CantBeCopied result;
|
|
|
327 return result; // Legal C++, but does not compile with Ubuntu 18.04 default g++
|
|
|
328 }
|
|
|
329 std::optional<CantBeCopied> fooOK() {
|
|
|
330 CantBeCopied result;
|
|
|
331 return {std::move(result)}; // Compiles OK everywhere
|
|
|
332 }
|
|
|
333 ```
|
|
|
334 The underlying bug is actually not specific to `std::optional` but this is the most common
|
|
|
335 case in f18 where the issue may occur. The actual bug can be reproduced with any class `B`
|
|
|
336 that has a perfect forwarding constructor taking `CantBeCopied` as argument:
|
|
|
337 `template<typename CantBeCopied> B(CantBeCopied&& x) x_{std::forward<CantBeCopied>(x)} {}`.
|
|
|
338 In such scenarios, Ubuntu 18.04 g++ fails to instantiate the move constructor
|
|
|
339 and to construct the returned value as it should, instead it complains about a
|
|
|
340 missing copy constructor.
|
|
|
341
|
|
|
342 Local result variables do not need to and should not be explicitly moved into optionals
|
|
|
343 if they have a copy constructor.
|
