llvm.org GIT mirror llvm / 7066282
Revert my commit in r199620 that added sections about namespaces to the coding standards, and instead fix the existing section. Thanks to Daniel Jasper for pointing out we already had a section devoted to this topic. Instead of adding sections, just hack on this section some. Also fix the example in the anonymous namespace section below it to agree with the new advice. As a re-cap, this switches the LLVM preferred style to never indent namespaces. Having two approaches just led to endless (and utterly pointless) debates about what was "small enough". This wasn't helping anyone. The no-indent rule is easy to understand and doesn't really make anything harder to read. Moreover, with tools like clang-format it is considerably nicer to have simple consistent rules. git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@199637 91177308-0d34-0410-b5e6-96231b3b80d8 Chandler Carruth 6 years ago
1 changed file(s) with 33 addition(s) and 112 deletion(s). Raw diff Collapse all Expand all
105105 to the paper where it is published should be included, as well as any notes or
106106 *gotchas* in the code to watch out for.
107107
108 Namespace Markers
109 """""""""""""""""
110
111 We don't indent namespaces (see below) and so feel free to add markers to the
112 end of a namespace where it helps readabilitily:
113
114 .. code-block:: c++
115
116 namespace foo {
117
118 // Lots of code here...
119
120 } // End foo namespace
121
122 This isn't required, and in many cases (such as the namespace used for an
123 entire file like the 'llvm' namespace in header files) it isn't really useful.
124 Use your judgment and add it where it helps.
125
126108 Class overviews
127109 """""""""""""""
128110
353335
354336 Okay, in your first year of programming you were told that indentation is
355337 important. If you didn't believe and internalize this then, now is the time.
356 Just do it. A few cases are called out here that have common alternatives. The
357 intent in saying which way to format things is to increase consistency across
358 the LLVM codebase.
359
360 Namespaces
361 """"""""""
362
363 A simple rule: don't indent them. Here are examples of well formatted and
364 indented namespaces:
365
366 .. code-block:: c++
367 namespace llvm {
368
369 namespace foo {
370 class A;
371 class B;
372 }
373
374 namespace {
375 /// \brief Some local class definition.
376 /// ...
377 class Widget {
378 // ... lots of code here ...
379 };
380 } // End anonymous namespace
381
382 } // End llvm namespace
338 Just do it.
383339
384340 Compiler Issues
385341 ---------------
12331189
12341190 In general, we strive to reduce indentation wherever possible. This is useful
12351191 because we want code to `fit into 80 columns`_ without wrapping horribly, but
1236 also because it makes it easier to understand the code. Namespaces are a funny
1237 thing: they are often large, and we often desire to put lots of stuff into them
1238 (so they can be large). Other times they are tiny, because they just hold an
1239 enum or something similar. In order to balance this, we use different
1240 approaches for small versus large namespaces.
1241
1242 If a namespace definition is small and *easily* fits on a screen (say, less than
1243 35 lines of code), then you should indent its body. Here's an example:
1244
1245 .. code-block:: c++
1246
1247 namespace llvm {
1248 namespace X86 {
1249 /// \brief An enum for the x86 relocation codes. Note that
1250 /// the terminology here doesn't follow x86 convention - word means
1251 /// 32-bit and dword means 64-bit.
1252 enum RelocationType {
1253 /// \brief PC relative relocation, add the relocated value to
1254 /// the value already in memory, after we adjust it for where the PC is.
1255 reloc_pcrel_word = 0,
1256
1257 /// \brief PIC base relative relocation, add the relocated value to
1258 /// the value already in memory, after we adjust it for where the
1259 /// PIC base is.
1260 reloc_picrel_word = 1,
1261
1262 /// \brief Absolute relocation, just add the relocated value to the
1263 /// value already in memory.
1264 reloc_absolute_word = 2,
1265 reloc_absolute_dword = 3
1266 };
1267 }
1268 }
1269
1270 Since the body is small, indenting adds value because it makes it very clear
1271 where the namespace starts and ends, and it is easy to take the whole thing in
1272 in one "gulp" when reading the code. If the blob of code in the namespace is
1273 larger (as it typically is in a header in the ``llvm`` or ``clang`` namespaces),
1274 do not indent the code, and add a comment indicating what namespace is being
1275 closed. For example:
1192 also because it makes it easier to understand the code. To facilitate this and
1193 avoid some insanely deep nesting on occasion, don't indent namespaces. If it
1194 helps readability, feel free to add a comment indicating what namespace is
1195 being closed by a ``}``. For example:
12761196
12771197 .. code-block:: c++
12781198
12941214 } // end namespace knowledge
12951215 } // end namespace llvm
12961216
1297 Because the class is large, we don't expect that the reader can easily
1298 understand the entire concept in a glance, and the end of the file (where the
1299 namespaces end) may be a long ways away from the place they open. As such,
1300 indenting the contents of the namespace doesn't add any value, and detracts from
1301 the readability of the class. In these cases it is best to *not* indent the
1302 contents of the namespace.
1217
1218 Feel free to skip the closing comment when the namespace being closed is
1219 obvious for any reason. For example, the outer-most namespace in a header file
1220 is rarely a source of confusion. But namespaces both anonymous and named in
1221 source files that are being closed half way through the file probably could use
1222 clarification.
13031223
13041224 .. _static:
13051225
13281248 .. code-block:: c++
13291249
13301250 namespace {
1331 class StringSort {
1332 ...
1333 public:
1334 StringSort(...)
1335 bool operator<(const char *RHS) const;
1336 };
1337 } // end anonymous namespace
1338
1339 static void runHelper() {
1340 ...
1341 }
1342
1343 bool StringSort::operator<(const char *RHS) const {
1344 ...
1345 }
1346
1347 This is bad:
1348
1349 .. code-block:: c++
1350
1351 namespace {
13521251 class StringSort {
13531252 ...
13541253 public:
13551254 StringSort(...)
13561255 bool operator<(const char *RHS) const;
13571256 };
1257 } // end anonymous namespace
1258
1259 static void runHelper() {
1260 ...
1261 }
1262
1263 bool StringSort::operator<(const char *RHS) const {
1264 ...
1265 }
1266
1267 This is bad:
1268
1269 .. code-block:: c++
1270
1271 namespace {
1272
1273 class StringSort {
1274 ...
1275 public:
1276 StringSort(...)
1277 bool operator<(const char *RHS) const;
1278 };
13581279
13591280 void runHelper() {
13601281 ...