1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
|
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>LLVM Coding Standards — LLVM 13 documentation</title>
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
<script id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
<script src="_static/jquery.js"></script>
<script src="_static/underscore.js"></script>
<script src="_static/doctools.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Bisecting LLVM code" href="GitBisecting.html" />
<link rel="prev" title="LLVM Bug Life Cycle" href="BugLifeCycle.html" />
<style type="text/css">
table.right { float: right; margin-left: 20px; }
table.right td { border: 1px solid #ccc; }
</style>
</head><body>
<div class="logo">
<a href="index.html">
<img src="_static/logo.png"
alt="LLVM Logo" width="250" height="88"/></a>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="GitBisecting.html" title="Bisecting LLVM code"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="BugLifeCycle.html" title="LLVM Bug Life Cycle"
accesskey="P">previous</a> |</li>
<li><a href="https://llvm.org/">LLVM Home</a> | </li>
<li><a href="index.html">Documentation</a>»</li>
<li class="nav-item nav-item-1"><a href="GettingInvolved.html" accesskey="U">Getting Involved</a> »</li>
<li class="nav-item nav-item-this"><a href="">LLVM Coding Standards</a></li>
</ul>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3>Documentation</h3>
<ul class="want-points">
<li><a href="https://llvm.org/docs/GettingStartedTutorials.html">Getting Started/Tutorials</a></li>
<li><a href="https://llvm.org/docs/UserGuides.html">User Guides</a></li>
<li><a href="https://llvm.org/docs/Reference.html">Reference</a></li>
</ul>
<h3>Getting Involved</h3>
<ul class="want-points">
<li><a href="https://llvm.org/docs/Contributing.html">Contributing to LLVM</a></li>
<li><a href="https://llvm.org/docs/HowToSubmitABug.html">Submitting Bug Reports</a></li>
<li><a href="https://llvm.org/docs/GettingInvolved.html#mailing-lists">Mailing Lists</a></li>
<li><a href="https://llvm.org/docs/GettingInvolved.html#irc">IRC</a></li>
<li><a href="https://llvm.org/docs/GettingInvolved.html#meetups-and-social-events">Meetups and Social Events</a></li>
</ul>
<h3>Additional Links</h3>
<ul class="want-points">
<li><a href="https://llvm.org/docs/FAQ.html">FAQ</a></li>
<li><a href="https://llvm.org/docs/Lexicon.html">Glossary</a></li>
<li><a href="https://llvm.org/pubs">Publications</a></li>
<li><a href="https://github.com/llvm/llvm-project//">Github Repository</a></li>
</ul>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/CodingStandards.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" />
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>$('#searchbox').show(0);</script>
</div>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="llvm-coding-standards">
<h1>LLVM Coding Standards<a class="headerlink" href="#llvm-coding-standards" title="Permalink to this headline">¶</a></h1>
<div class="contents local topic" id="contents">
<ul class="simple">
<li><p><a class="reference internal" href="#introduction" id="id1">Introduction</a></p></li>
<li><p><a class="reference internal" href="#languages-libraries-and-standards" id="id2">Languages, Libraries, and Standards</a></p>
<ul>
<li><p><a class="reference internal" href="#c-standard-versions" id="id3">C++ Standard Versions</a></p></li>
<li><p><a class="reference internal" href="#c-standard-library" id="id4">C++ Standard Library</a></p></li>
<li><p><a class="reference internal" href="#guidelines-for-go-code" id="id5">Guidelines for Go code</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#mechanical-source-issues" id="id6">Mechanical Source Issues</a></p>
<ul>
<li><p><a class="reference internal" href="#source-code-formatting" id="id7">Source Code Formatting</a></p>
<ul>
<li><p><a class="reference internal" href="#commenting" id="id8">Commenting</a></p>
<ul>
<li><p><a class="reference internal" href="#file-headers" id="id9">File Headers</a></p></li>
<li><p><a class="reference internal" href="#header-guard" id="id10">Header Guard</a></p></li>
<li><p><a class="reference internal" href="#class-overviews" id="id11">Class overviews</a></p></li>
<li><p><a class="reference internal" href="#method-information" id="id12">Method information</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#comment-formatting" id="id13">Comment Formatting</a></p></li>
<li><p><a class="reference internal" href="#doxygen-use-in-documentation-comments" id="id14">Doxygen Use in Documentation Comments</a></p></li>
<li><p><a class="reference internal" href="#error-and-warning-messages" id="id15">Error and Warning Messages</a></p></li>
<li><p><a class="reference internal" href="#include-style" id="id16"><code class="docutils literal notranslate"><span class="pre">#include</span></code> Style</a></p></li>
<li><p><a class="reference internal" href="#source-code-width" id="id17">Source Code Width</a></p></li>
<li><p><a class="reference internal" href="#whitespace" id="id18">Whitespace</a></p>
<ul>
<li><p><a class="reference internal" href="#format-lambdas-like-blocks-of-code" id="id19">Format Lambdas Like Blocks Of Code</a></p></li>
<li><p><a class="reference internal" href="#braced-initializer-lists" id="id20">Braced Initializer Lists</a></p></li>
</ul>
</li>
</ul>
</li>
<li><p><a class="reference internal" href="#language-and-compiler-issues" id="id21">Language and Compiler Issues</a></p>
<ul>
<li><p><a class="reference internal" href="#treat-compiler-warnings-like-errors" id="id22">Treat Compiler Warnings Like Errors</a></p></li>
<li><p><a class="reference internal" href="#write-portable-code" id="id23">Write Portable Code</a></p></li>
<li><p><a class="reference internal" href="#do-not-use-rtti-or-exceptions" id="id24">Do not use RTTI or Exceptions</a></p></li>
<li><p><a class="reference internal" href="#do-not-use-static-constructors" id="id25">Do not use Static Constructors</a></p></li>
<li><p><a class="reference internal" href="#use-of-class-and-struct-keywords" id="id26">Use of <code class="docutils literal notranslate"><span class="pre">class</span></code> and <code class="docutils literal notranslate"><span class="pre">struct</span></code> Keywords</a></p></li>
<li><p><a class="reference internal" href="#do-not-use-braced-initializer-lists-to-call-a-constructor" id="id27">Do not use Braced Initializer Lists to Call a Constructor</a></p></li>
<li><p><a class="reference internal" href="#use-auto-type-deduction-to-make-code-more-readable" id="id28">Use <code class="docutils literal notranslate"><span class="pre">auto</span></code> Type Deduction to Make Code More Readable</a></p></li>
<li><p><a class="reference internal" href="#beware-unnecessary-copies-with-auto" id="id29">Beware unnecessary copies with <code class="docutils literal notranslate"><span class="pre">auto</span></code></a></p></li>
<li><p><a class="reference internal" href="#beware-of-non-determinism-due-to-ordering-of-pointers" id="id30">Beware of non-determinism due to ordering of pointers</a></p></li>
<li><p><a class="reference internal" href="#beware-of-non-deterministic-sorting-order-of-equal-elements" id="id31">Beware of non-deterministic sorting order of equal elements</a></p></li>
</ul>
</li>
</ul>
</li>
<li><p><a class="reference internal" href="#style-issues" id="id32">Style Issues</a></p>
<ul>
<li><p><a class="reference internal" href="#the-high-level-issues" id="id33">The High-Level Issues</a></p>
<ul>
<li><p><a class="reference internal" href="#self-contained-headers" id="id34">Self-contained Headers</a></p></li>
<li><p><a class="reference internal" href="#library-layering" id="id35">Library Layering</a></p></li>
<li><p><a class="reference internal" href="#include-as-little-as-possible" id="id36"><code class="docutils literal notranslate"><span class="pre">#include</span></code> as Little as Possible</a></p></li>
<li><p><a class="reference internal" href="#keep-internal-headers-private" id="id37">Keep “Internal” Headers Private</a></p></li>
<li><p><a class="reference internal" href="#use-namespace-qualifiers-to-implement-previously-declared-functions" id="id38">Use Namespace Qualifiers to Implement Previously Declared Functions</a></p></li>
<li><p><a class="reference internal" href="#use-early-exits-and-continue-to-simplify-code" id="id39">Use Early Exits and <code class="docutils literal notranslate"><span class="pre">continue</span></code> to Simplify Code</a></p></li>
<li><p><a class="reference internal" href="#don-t-use-else-after-a-return" id="id40">Don’t use <code class="docutils literal notranslate"><span class="pre">else</span></code> after a <code class="docutils literal notranslate"><span class="pre">return</span></code></a></p></li>
<li><p><a class="reference internal" href="#turn-predicate-loops-into-predicate-functions" id="id41">Turn Predicate Loops into Predicate Functions</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#the-low-level-issues" id="id42">The Low-Level Issues</a></p>
<ul>
<li><p><a class="reference internal" href="#name-types-functions-variables-and-enumerators-properly" id="id43">Name Types, Functions, Variables, and Enumerators Properly</a></p></li>
<li><p><a class="reference internal" href="#assert-liberally" id="id44">Assert Liberally</a></p></li>
<li><p><a class="reference internal" href="#do-not-use-using-namespace-std" id="id45">Do Not Use <code class="docutils literal notranslate"><span class="pre">using</span> <span class="pre">namespace</span> <span class="pre">std</span></code></a></p></li>
<li><p><a class="reference internal" href="#provide-a-virtual-method-anchor-for-classes-in-headers" id="id46">Provide a Virtual Method Anchor for Classes in Headers</a></p></li>
<li><p><a class="reference internal" href="#don-t-use-default-labels-in-fully-covered-switches-over-enumerations" id="id47">Don’t use default labels in fully covered switches over enumerations</a></p></li>
<li><p><a class="reference internal" href="#use-range-based-for-loops-wherever-possible" id="id48">Use range-based <code class="docutils literal notranslate"><span class="pre">for</span></code> loops wherever possible</a></p></li>
<li><p><a class="reference internal" href="#don-t-evaluate-end-every-time-through-a-loop" id="id49">Don’t evaluate <code class="docutils literal notranslate"><span class="pre">end()</span></code> every time through a loop</a></p></li>
<li><p><a class="reference internal" href="#include-iostream-is-forbidden" id="id50"><code class="docutils literal notranslate"><span class="pre">#include</span> <span class="pre"><iostream></span></code> is Forbidden</a></p></li>
<li><p><a class="reference internal" href="#use-raw-ostream" id="id51">Use <code class="docutils literal notranslate"><span class="pre">raw_ostream</span></code></a></p></li>
<li><p><a class="reference internal" href="#avoid-std-endl" id="id52">Avoid <code class="docutils literal notranslate"><span class="pre">std::endl</span></code></a></p></li>
<li><p><a class="reference internal" href="#don-t-use-inline-when-defining-a-function-in-a-class-definition" id="id53">Don’t use <code class="docutils literal notranslate"><span class="pre">inline</span></code> when defining a function in a class definition</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#microscopic-details" id="id54">Microscopic Details</a></p>
<ul>
<li><p><a class="reference internal" href="#spaces-before-parentheses" id="id55">Spaces Before Parentheses</a></p></li>
<li><p><a class="reference internal" href="#prefer-preincrement" id="id56">Prefer Preincrement</a></p></li>
<li><p><a class="reference internal" href="#namespace-indentation" id="id57">Namespace Indentation</a></p></li>
<li><p><a class="reference internal" href="#anonymous-namespaces" id="id58">Anonymous Namespaces</a></p></li>
<li><p><a class="reference internal" href="#don-t-use-braces-on-simple-single-statement-bodies-of-if-else-loop-statements" id="id59">Don’t Use Braces on Simple Single-Statement Bodies of if/else/loop Statements</a></p></li>
</ul>
</li>
</ul>
</li>
<li><p><a class="reference internal" href="#see-also" id="id60">See Also</a></p></li>
</ul>
</div>
<div class="section" id="introduction">
<h2><a class="toc-backref" href="#id1">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
<p>This document describes coding standards that are used in the LLVM project.
Although no coding standards should be regarded as absolute requirements to be
followed in all instances, coding standards are
particularly important for large-scale code bases that follow a library-based
design (like LLVM).</p>
<p>While this document may provide guidance for some mechanical formatting issues,
whitespace, or other “microscopic details”, these are not fixed standards.
Always follow the golden rule:</p>
<blockquote id="golden-rule">
<div><p><strong>If you are extending, enhancing, or bug fixing already implemented code,
use the style that is already being used so that the source is uniform and
easy to follow.</strong></p>
</div></blockquote>
<p>Note that some code bases (e.g. <code class="docutils literal notranslate"><span class="pre">libc++</span></code>) have special reasons to deviate
from the coding standards. For example, in the case of <code class="docutils literal notranslate"><span class="pre">libc++</span></code>, this is
because the naming and other conventions are dictated by the C++ standard.</p>
<p>There are some conventions that are not uniformly followed in the code base
(e.g. the naming convention). This is because they are relatively new, and a
lot of code was written before they were put in place. Our long term goal is
for the entire codebase to follow the convention, but we explicitly <em>do not</em>
want patches that do large-scale reformatting of existing code. On the other
hand, it is reasonable to rename the methods of a class if you’re about to
change it in some other way. Please commit such changes separately to
make code review easier.</p>
<p>The ultimate goal of these guidelines is to increase the readability and
maintainability of our common source base.</p>
</div>
<div class="section" id="languages-libraries-and-standards">
<h2><a class="toc-backref" href="#id2">Languages, Libraries, and Standards</a><a class="headerlink" href="#languages-libraries-and-standards" title="Permalink to this headline">¶</a></h2>
<p>Most source code in LLVM and other LLVM projects using these coding standards
is C++ code. There are some places where C code is used either due to
environment restrictions, historical restrictions, or due to third-party source
code imported into the tree. Generally, our preference is for standards
conforming, modern, and portable C++ code as the implementation language of
choice.</p>
<div class="section" id="c-standard-versions">
<h3><a class="toc-backref" href="#id3">C++ Standard Versions</a><a class="headerlink" href="#c-standard-versions" title="Permalink to this headline">¶</a></h3>
<p>Unless otherwise documented, LLVM subprojects are written using standard C++14
code and avoid unnecessary vendor-specific extensions.</p>
<p>Nevertheless, we restrict ourselves to features which are available in the
major toolchains supported as host compilers (see <a class="reference internal" href="GettingStarted.html"><span class="doc">Getting Started with the LLVM System</span></a> page,
section <cite>Software</cite>).</p>
<p>Each toolchain provides a good reference for what it accepts:</p>
<ul class="simple">
<li><p>Clang: <a class="reference external" href="https://clang.llvm.org/cxx_status.html">https://clang.llvm.org/cxx_status.html</a></p></li>
<li><p>GCC: <a class="reference external" href="https://gcc.gnu.org/projects/cxx-status.html#cxx14">https://gcc.gnu.org/projects/cxx-status.html#cxx14</a></p></li>
<li><p>MSVC: <a class="reference external" href="https://msdn.microsoft.com/en-us/library/hh567368.aspx">https://msdn.microsoft.com/en-us/library/hh567368.aspx</a></p></li>
</ul>
</div>
<div class="section" id="c-standard-library">
<h3><a class="toc-backref" href="#id4">C++ Standard Library</a><a class="headerlink" href="#c-standard-library" title="Permalink to this headline">¶</a></h3>
<p>Instead of implementing custom data structures, we encourage the use of C++
standard library facilities or LLVM support libraries whenever they are
available for a particular task. LLVM and related projects emphasize and rely
on the standard library facilities and the LLVM support libraries as much as
possible.</p>
<p>LLVM support libraries (for example, <a class="reference external" href="https://github.com/llvm/llvm-project/tree/main/llvm/include/llvm/ADT">ADT</a>)
implement specialized data structures or functionality missing in the standard
library. Such libraries are usually implemented in the <code class="docutils literal notranslate"><span class="pre">llvm</span></code> namespace and
follow the expected standard interface, when there is one.</p>
<p>When both C++ and the LLVM support libraries provide similar functionality, and
there isn’t a specific reason to favor the C++ implementation, it is generally
preferable to use the LLVM library. For example, <code class="docutils literal notranslate"><span class="pre">llvm::DenseMap</span></code> should
almost always be used instead of <code class="docutils literal notranslate"><span class="pre">std::map</span></code> or <code class="docutils literal notranslate"><span class="pre">std::unordered_map</span></code>, and
<code class="docutils literal notranslate"><span class="pre">llvm::SmallVector</span></code> should usually be used instead of <code class="docutils literal notranslate"><span class="pre">std::vector</span></code>.</p>
<p>We explicitly avoid some standard facilities, like the I/O streams, and instead
use LLVM’s streams library (<a class="reference internal" href="#raw-ostream">raw_ostream</a>). More detailed information on these
subjects is available in the <a class="reference internal" href="ProgrammersManual.html"><span class="doc">LLVM Programmer’s Manual</span></a>.</p>
<p>For more information about LLVM’s data structures and the tradeoffs they make,
please consult [that section of the programmer’s
manual](<a class="reference external" href="https://llvm.org/docs/ProgrammersManual.html#picking-the-right-data-structure-for-a-task">https://llvm.org/docs/ProgrammersManual.html#picking-the-right-data-structure-for-a-task</a>).</p>
</div>
<div class="section" id="guidelines-for-go-code">
<h3><a class="toc-backref" href="#id5">Guidelines for Go code</a><a class="headerlink" href="#guidelines-for-go-code" title="Permalink to this headline">¶</a></h3>
<p>Any code written in the Go programming language is not subject to the
formatting rules below. Instead, we adopt the formatting rules enforced by
the <a class="reference external" href="https://golang.org/cmd/gofmt/">gofmt</a> tool.</p>
<p>Go code should strive to be idiomatic. Two good sets of guidelines for what
this means are <a class="reference external" href="https://golang.org/doc/effective_go.html">Effective Go</a> and <a class="reference external" href="https://github.com/golang/go/wiki/CodeReviewComments">Go Code Review Comments</a>.</p>
</div>
</div>
<div class="section" id="mechanical-source-issues">
<h2><a class="toc-backref" href="#id6">Mechanical Source Issues</a><a class="headerlink" href="#mechanical-source-issues" title="Permalink to this headline">¶</a></h2>
<div class="section" id="source-code-formatting">
<h3><a class="toc-backref" href="#id7">Source Code Formatting</a><a class="headerlink" href="#source-code-formatting" title="Permalink to this headline">¶</a></h3>
<div class="section" id="commenting">
<h4><a class="toc-backref" href="#id8">Commenting</a><a class="headerlink" href="#commenting" title="Permalink to this headline">¶</a></h4>
<p>Comments are important for readability and maintainability. When writing comments,
write them as English prose, using proper capitalization, punctuation, etc.
Aim to describe what the code is trying to do and why, not <em>how</em> it does it at
a micro level. Here are a few important things to document:</p>
<div class="section" id="file-headers">
<span id="header-file-comment"></span><h5><a class="toc-backref" href="#id9">File Headers</a><a class="headerlink" href="#file-headers" title="Permalink to this headline">¶</a></h5>
<p>Every source file should have a header on it that describes the basic purpose of
the file. The standard header looks like this:</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="c1">//===-- llvm/Instruction.h - Instruction class definition -------*- C++ -*-===//</span>
<span class="c1">//</span>
<span class="c1">// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.</span>
<span class="c1">// See https://llvm.org/LICENSE.txt for license information.</span>
<span class="c1">// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception</span>
<span class="c1">//</span>
<span class="c1">//===----------------------------------------------------------------------===//</span>
<span class="c1">///</span>
<span class="c1">/// \file</span>
<span class="c1">/// This file contains the declaration of the Instruction class, which is the</span>
<span class="c1">/// base class for all of the VM instructions.</span>
<span class="c1">///</span>
<span class="c1">//===----------------------------------------------------------------------===//</span>
</pre></div>
</div>
<p>A few things to note about this particular format: The “<code class="docutils literal notranslate"><span class="pre">-*-</span> <span class="pre">C++</span> <span class="pre">-*-</span></code>” string
on the first line is there to tell Emacs that the source file is a C++ file, not
a C file (Emacs assumes <code class="docutils literal notranslate"><span class="pre">.h</span></code> files are C files by default).</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>This tag is not necessary in <code class="docutils literal notranslate"><span class="pre">.cpp</span></code> files. The name of the file is also
on the first line, along with a very short description of the purpose of the
file.</p>
</div>
<p>The next section in the file is a concise note that defines the license that the
file is released under. This makes it perfectly clear what terms the source
code can be distributed under and should not be modified in any way.</p>
<p>The main body is a <a class="reference external" href="http://www.doxygen.nl/">Doxygen</a> comment (identified by
the <code class="docutils literal notranslate"><span class="pre">///</span></code> comment marker instead of the usual <code class="docutils literal notranslate"><span class="pre">//</span></code>) describing the purpose
of the file. The first sentence (or a passage beginning with <code class="docutils literal notranslate"><span class="pre">\brief</span></code>) is
used as an abstract. Any additional information should be separated by a blank
line. If an algorithm is based on a paper or is described in another source,
provide a reference.</p>
</div>
<div class="section" id="header-guard">
<h5><a class="toc-backref" href="#id10">Header Guard</a><a class="headerlink" href="#header-guard" title="Permalink to this headline">¶</a></h5>
<p>The header file’s guard should be the all-caps path that a user of this header
would #include, using ‘_’ instead of path separator and extension marker.
For example, the header file
<code class="docutils literal notranslate"><span class="pre">llvm/include/llvm/Analysis/Utils/Local.h</span></code> would be <code class="docutils literal notranslate"><span class="pre">#include</span></code>-ed as
<code class="docutils literal notranslate"><span class="pre">#include</span> <span class="pre">"llvm/Analysis/Utils/Local.h"</span></code>, so its guard is
<code class="docutils literal notranslate"><span class="pre">LLVM_ANALYSIS_UTILS_LOCAL_H</span></code>.</p>
</div>
<div class="section" id="class-overviews">
<h5><a class="toc-backref" href="#id11">Class overviews</a><a class="headerlink" href="#class-overviews" title="Permalink to this headline">¶</a></h5>
<p>Classes are a fundamental part of an object-oriented design. As such, a
class definition should have a comment block that explains what the class is
used for and how it works. Every non-trivial class is expected to have a
<code class="docutils literal notranslate"><span class="pre">doxygen</span></code> comment block.</p>
</div>
<div class="section" id="method-information">
<h5><a class="toc-backref" href="#id12">Method information</a><a class="headerlink" href="#method-information" title="Permalink to this headline">¶</a></h5>
<p>Methods and global functions should also be documented. A quick note about
what it does and a description of the edge cases is all that is necessary here.
The reader should be able to understand how to use interfaces without reading
the code itself.</p>
<p>Good things to talk about here are what happens when something unexpected
happens, for instance, does the method return null?</p>
</div>
</div>
<div class="section" id="comment-formatting">
<h4><a class="toc-backref" href="#id13">Comment Formatting</a><a class="headerlink" href="#comment-formatting" title="Permalink to this headline">¶</a></h4>
<p>In general, prefer C++-style comments (<code class="docutils literal notranslate"><span class="pre">//</span></code> for normal comments, <code class="docutils literal notranslate"><span class="pre">///</span></code> for
<code class="docutils literal notranslate"><span class="pre">doxygen</span></code> documentation comments). There are a few cases when it is
useful to use C-style (<code class="docutils literal notranslate"><span class="pre">/*</span> <span class="pre">*/</span></code>) comments however:</p>
<ol class="arabic">
<li><p>When writing C code to be compatible with C89.</p></li>
<li><p>When writing a header file that may be <code class="docutils literal notranslate"><span class="pre">#include</span></code>d by a C source file.</p></li>
<li><p>When writing a source file that is used by a tool that only accepts C-style
comments.</p></li>
<li><p>When documenting the significance of constants used as actual parameters in
a call. This is most helpful for <code class="docutils literal notranslate"><span class="pre">bool</span></code> parameters, or passing <code class="docutils literal notranslate"><span class="pre">0</span></code> or
<code class="docutils literal notranslate"><span class="pre">nullptr</span></code>. The comment should contain the parameter name, which ought to be
meaningful. For example, it’s not clear what the parameter means in this call:</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">Object</span><span class="p">.</span><span class="n">emitName</span><span class="p">(</span><span class="k">nullptr</span><span class="p">);</span>
</pre></div>
</div>
<p>An in-line C-style comment makes the intent obvious:</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">Object</span><span class="p">.</span><span class="n">emitName</span><span class="p">(</span><span class="cm">/*Prefix=*/</span><span class="k">nullptr</span><span class="p">);</span>
</pre></div>
</div>
</li>
</ol>
<p>Commenting out large blocks of code is discouraged, but if you really have to do
this (for documentation purposes or as a suggestion for debug printing), use
<code class="docutils literal notranslate"><span class="pre">#if</span> <span class="pre">0</span></code> and <code class="docutils literal notranslate"><span class="pre">#endif</span></code>. These nest properly and are better behaved in general
than C style comments.</p>
</div>
<div class="section" id="doxygen-use-in-documentation-comments">
<h4><a class="toc-backref" href="#id14">Doxygen Use in Documentation Comments</a><a class="headerlink" href="#doxygen-use-in-documentation-comments" title="Permalink to this headline">¶</a></h4>
<p>Use the <code class="docutils literal notranslate"><span class="pre">\file</span></code> command to turn the standard file header into a file-level
comment.</p>
<p>Include descriptive paragraphs for all public interfaces (public classes,
member and non-member functions). Avoid restating the information that can
be inferred from the API name. The first sentence (or a paragraph beginning
with <code class="docutils literal notranslate"><span class="pre">\brief</span></code>) is used as an abstract. Try to use a single sentence as the
<code class="docutils literal notranslate"><span class="pre">\brief</span></code> adds visual clutter. Put detailed discussion into separate
paragraphs.</p>
<p>To refer to parameter names inside a paragraph, use the <code class="docutils literal notranslate"><span class="pre">\p</span> <span class="pre">name</span></code> command.
Don’t use the <code class="docutils literal notranslate"><span class="pre">\arg</span> <span class="pre">name</span></code> command since it starts a new paragraph that
contains documentation for the parameter.</p>
<p>Wrap non-inline code examples in <code class="docutils literal notranslate"><span class="pre">\code</span> <span class="pre">...</span> <span class="pre">\endcode</span></code>.</p>
<p>To document a function parameter, start a new paragraph with the
<code class="docutils literal notranslate"><span class="pre">\param</span> <span class="pre">name</span></code> command. If the parameter is used as an out or an in/out
parameter, use the <code class="docutils literal notranslate"><span class="pre">\param</span> <span class="pre">[out]</span> <span class="pre">name</span></code> or <code class="docutils literal notranslate"><span class="pre">\param</span> <span class="pre">[in,out]</span> <span class="pre">name</span></code> command,
respectively.</p>
<p>To describe function return value, start a new paragraph with the <code class="docutils literal notranslate"><span class="pre">\returns</span></code>
command.</p>
<p>A minimal documentation comment:</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="c1">/// Sets the xyzzy property to \p Baz.</span>
<span class="kt">void</span> <span class="nf">setXyzzy</span><span class="p">(</span><span class="kt">bool</span> <span class="n">Baz</span><span class="p">);</span>
</pre></div>
</div>
<p>A documentation comment that uses all Doxygen features in a preferred way:</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="c1">/// Does foo and bar.</span>
<span class="c1">///</span>
<span class="c1">/// Does not do foo the usual way if \p Baz is true.</span>
<span class="c1">///</span>
<span class="c1">/// Typical usage:</span>
<span class="c1">/// \code</span>
<span class="c1">/// fooBar(false, "quux", Res);</span>
<span class="c1">/// \endcode</span>
<span class="c1">///</span>
<span class="c1">/// \param Quux kind of foo to do.</span>
<span class="c1">/// \param [out] Result filled with bar sequence on foo success.</span>
<span class="c1">///</span>
<span class="c1">/// \returns true on success.</span>
<span class="kt">bool</span> <span class="nf">fooBar</span><span class="p">(</span><span class="kt">bool</span> <span class="n">Baz</span><span class="p">,</span> <span class="n">StringRef</span> <span class="n">Quux</span><span class="p">,</span> <span class="n">std</span><span class="o">::</span><span class="n">vector</span><span class="o"><</span><span class="kt">int</span><span class="o">></span> <span class="o">&</span><span class="n">Result</span><span class="p">);</span>
</pre></div>
</div>
<p>Don’t duplicate the documentation comment in the header file and in the
implementation file. Put the documentation comments for public APIs into the
header file. Documentation comments for private APIs can go to the
implementation file. In any case, implementation files can include additional
comments (not necessarily in Doxygen markup) to explain implementation details
as needed.</p>
<p>Don’t duplicate function or class name at the beginning of the comment.
For humans it is obvious which function or class is being documented;
automatic documentation processing tools are smart enough to bind the comment
to the correct declaration.</p>
<p>Avoid:</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="c1">// Example.h:</span>
<span class="c1">// example - Does something important.</span>
<span class="kt">void</span> <span class="nf">example</span><span class="p">();</span>
<span class="c1">// Example.cpp:</span>
<span class="c1">// example - Does something important.</span>
<span class="kt">void</span> <span class="nf">example</span><span class="p">()</span> <span class="p">{</span> <span class="p">...</span> <span class="p">}</span>
</pre></div>
</div>
<p>Preferred:</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="c1">// Example.h:</span>
<span class="c1">/// Does something important.</span>
<span class="kt">void</span> <span class="nf">example</span><span class="p">();</span>
<span class="c1">// Example.cpp:</span>
<span class="c1">/// Builds a B-tree in order to do foo. See paper by...</span>
<span class="kt">void</span> <span class="nf">example</span><span class="p">()</span> <span class="p">{</span> <span class="p">...</span> <span class="p">}</span>
</pre></div>
</div>
</div>
<div class="section" id="error-and-warning-messages">
<h4><a class="toc-backref" href="#id15">Error and Warning Messages</a><a class="headerlink" href="#error-and-warning-messages" title="Permalink to this headline">¶</a></h4>
<p>Clear diagnostic messages are important to help users identify and fix issues in
their inputs. Use succinct but correct English prose that gives the user the
context needed to understand what went wrong. Also, to match error message
styles commonly produced by other tools, start the first sentence with a
lower-case letter, and finish the last sentence without a period, if it would
end in one otherwise. Sentences which end with different punctuation, such as
“did you forget ‘;’?”, should still do so.</p>
<p>For example this is a good error message:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>error: file.o: section header 3 is corrupt. Size is 10 when it should be 20
</pre></div>
</div>
<p>This is a bad message, since it does not provide useful information and uses the
wrong style:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>error: file.o: Corrupt section header.
</pre></div>
</div>
<p>As with other coding standards, individual projects, such as the Clang Static
Analyzer, may have preexisting styles that do not conform to this. If a
different formatting scheme is used consistently throughout the project, use
that style instead. Otherwise, this standard applies to all LLVM tools,
including clang, clang-tidy, and so on.</p>
<p>If the tool or project does not have existing functions to emit warnings or
errors, use the error and warning handlers provided in <code class="docutils literal notranslate"><span class="pre">Support/WithColor.h</span></code>
to ensure they are printed in the appropriate style, rather than printing to
stderr directly.</p>
<p>When using <code class="docutils literal notranslate"><span class="pre">report_fatal_error</span></code>, follow the same standards for the message as
regular error messages. Assertion messages and <code class="docutils literal notranslate"><span class="pre">llvm_unreachable</span></code> calls do not
necessarily need to follow these same styles as they are automatically
formatted, and thus these guidelines may not be suitable.</p>
</div>
<div class="section" id="include-style">
<h4><a class="toc-backref" href="#id16"><code class="docutils literal notranslate"><span class="pre">#include</span></code> Style</a><a class="headerlink" href="#include-style" title="Permalink to this headline">¶</a></h4>
<p>Immediately after the <a class="reference internal" href="#header-file-comment">header file comment</a> (and include guards if working on a
header file), the <a class="reference internal" href="#minimal-list-of-includes">minimal list of #includes</a> required by the file should be
listed. We prefer these <code class="docutils literal notranslate"><span class="pre">#include</span></code>s to be listed in this order:</p>
<span id="main-module-header"></span><ol class="arabic simple" id="local-private-headers">
<li><p>Main Module Header</p></li>
<li><p>Local/Private Headers</p></li>
<li><p>LLVM project/subproject headers (<code class="docutils literal notranslate"><span class="pre">clang/...</span></code>, <code class="docutils literal notranslate"><span class="pre">lldb/...</span></code>, <code class="docutils literal notranslate"><span class="pre">llvm/...</span></code>, etc)</p></li>
<li><p>System <code class="docutils literal notranslate"><span class="pre">#include</span></code>s</p></li>
</ol>
<p>and each category should be sorted lexicographically by the full path.</p>
<p>The <a class="reference internal" href="#main-module-header">Main Module Header</a> file applies to <code class="docutils literal notranslate"><span class="pre">.cpp</span></code> files which implement an
interface defined by a <code class="docutils literal notranslate"><span class="pre">.h</span></code> file. This <code class="docutils literal notranslate"><span class="pre">#include</span></code> should always be included
<strong>first</strong> regardless of where it lives on the file system. By including a
header file first in the <code class="docutils literal notranslate"><span class="pre">.cpp</span></code> files that implement the interfaces, we ensure
that the header does not have any hidden dependencies which are not explicitly
<code class="docutils literal notranslate"><span class="pre">#include</span></code>d in the header, but should be. It is also a form of documentation
in the <code class="docutils literal notranslate"><span class="pre">.cpp</span></code> file to indicate where the interfaces it implements are defined.</p>
<p>LLVM project and subproject headers should be grouped from most specific to least
specific, for the same reasons described above. For example, LLDB depends on
both clang and LLVM, and clang depends on LLVM. So an LLDB source file should
include <code class="docutils literal notranslate"><span class="pre">lldb</span></code> headers first, followed by <code class="docutils literal notranslate"><span class="pre">clang</span></code> headers, followed by
<code class="docutils literal notranslate"><span class="pre">llvm</span></code> headers, to reduce the possibility (for example) of an LLDB header
accidentally picking up a missing include due to the previous inclusion of that
header in the main source file or some earlier header file. clang should
similarly include its own headers before including llvm headers. This rule
applies to all LLVM subprojects.</p>
</div>
<div class="section" id="source-code-width">
<span id="fit-into-80-columns"></span><h4><a class="toc-backref" href="#id17">Source Code Width</a><a class="headerlink" href="#source-code-width" title="Permalink to this headline">¶</a></h4>
<p>Write your code to fit within 80 columns.</p>
<p>There must be some limit to the width of the code in
order to allow developers to have multiple files side-by-side in
windows on a modest display. If you are going to pick a width limit, it is
somewhat arbitrary but you might as well pick something standard. Going with 90
columns (for example) instead of 80 columns wouldn’t add any significant value
and would be detrimental to printing out code. Also many other projects have
standardized on 80 columns, so some people have already configured their editors
for it (vs something else, like 90 columns).</p>
</div>
<div class="section" id="whitespace">
<h4><a class="toc-backref" href="#id18">Whitespace</a><a class="headerlink" href="#whitespace" title="Permalink to this headline">¶</a></h4>
<p>In all cases, prefer spaces to tabs in source files. People have different
preferred indentation levels, and different styles of indentation that they
like; this is fine. What isn’t fine is that different editors/viewers expand
tabs out to different tab stops. This can cause your code to look completely
unreadable, and it is not worth dealing with.</p>
<p>As always, follow the <a class="reference internal" href="#golden-rule">Golden Rule</a> above: follow the style of existing code
if you are modifying and extending it.</p>
<p>Do not add trailing whitespace. Some common editors will automatically remove
trailing whitespace when saving a file which causes unrelated changes to appear
in diffs and commits.</p>
<div class="section" id="format-lambdas-like-blocks-of-code">
<h5><a class="toc-backref" href="#id19">Format Lambdas Like Blocks Of Code</a><a class="headerlink" href="#format-lambdas-like-blocks-of-code" title="Permalink to this headline">¶</a></h5>
<p>When formatting a multi-line lambda, format it like a block of code. If there
is only one multi-line lambda in a statement, and there are no expressions
lexically after it in the statement, drop the indent to the standard two space
indent for a block of code, as if it were an if-block opened by the preceding
part of the statement:</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">std</span><span class="o">::</span><span class="n">sort</span><span class="p">(</span><span class="n">foo</span><span class="p">.</span><span class="n">begin</span><span class="p">(),</span> <span class="n">foo</span><span class="p">.</span><span class="n">end</span><span class="p">(),</span> <span class="p">[</span><span class="o">&</span><span class="p">](</span><span class="n">Foo</span> <span class="n">a</span><span class="p">,</span> <span class="n">Foo</span> <span class="n">b</span><span class="p">)</span> <span class="o">-></span> <span class="kt">bool</span> <span class="p">{</span>
<span class="k">if</span> <span class="p">(</span><span class="n">a</span><span class="p">.</span><span class="n">blah</span> <span class="o"><</span> <span class="n">b</span><span class="p">.</span><span class="n">blah</span><span class="p">)</span>
<span class="k">return</span> <span class="nb">true</span><span class="p">;</span>
<span class="k">if</span> <span class="p">(</span><span class="n">a</span><span class="p">.</span><span class="n">baz</span> <span class="o"><</span> <span class="n">b</span><span class="p">.</span><span class="n">baz</span><span class="p">)</span>
<span class="k">return</span> <span class="nb">true</span><span class="p">;</span>
<span class="k">return</span> <span class="n">a</span><span class="p">.</span><span class="n">bam</span> <span class="o"><</span> <span class="n">b</span><span class="p">.</span><span class="n">bam</span><span class="p">;</span>
<span class="p">});</span>
</pre></div>
</div>
<p>To take best advantage of this formatting, if you are designing an API which
accepts a continuation or single callable argument (be it a function object, or
a <code class="docutils literal notranslate"><span class="pre">std::function</span></code>), it should be the last argument if at all possible.</p>
<p>If there are multiple multi-line lambdas in a statement, or additional
parameters after the lambda, indent the block two spaces from the indent of the
<code class="docutils literal notranslate"><span class="pre">[]</span></code>:</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">dyn_switch</span><span class="p">(</span><span class="n">V</span><span class="o">-></span><span class="n">stripPointerCasts</span><span class="p">(),</span>
<span class="p">[]</span> <span class="p">(</span><span class="n">PHINode</span> <span class="o">*</span><span class="n">PN</span><span class="p">)</span> <span class="p">{</span>
<span class="c1">// process phis...</span>
<span class="p">},</span>
<span class="p">[]</span> <span class="p">(</span><span class="n">SelectInst</span> <span class="o">*</span><span class="n">SI</span><span class="p">)</span> <span class="p">{</span>
<span class="c1">// process selects...</span>
<span class="p">},</span>
<span class="p">[]</span> <span class="p">(</span><span class="n">LoadInst</span> <span class="o">*</span><span class="n">LI</span><span class="p">)</span> <span class="p">{</span>
<span class="c1">// process loads...</span>
<span class="p">},</span>
<span class="p">[]</span> <span class="p">(</span><span class="n">AllocaInst</span> <span class="o">*</span><span class="n">AI</span><span class="p">)</span> <span class="p">{</span>
<span class="c1">// process allocas...</span>
<span class="p">});</span>
</pre></div>
</div>
</div>
<div class="section" id="braced-initializer-lists">
<h5><a class="toc-backref" href="#id20">Braced Initializer Lists</a><a class="headerlink" href="#braced-initializer-lists" title="Permalink to this headline">¶</a></h5>
<p>Starting from C++11, there are significantly more uses of braced lists to
perform initialization. For example, they can be used to construct aggregate
temporaries in expressions. They now have a natural way of ending up nested
within each other and within function calls in order to build up aggregates
(such as option structs) from local variables.</p>
<p>The historically common formatting of braced initialization of aggregate
variables does not mix cleanly with deep nesting, general expression contexts,
function arguments, and lambdas. We suggest new code use a simple rule for
formatting braced initialization lists: act as-if the braces were parentheses
in a function call. The formatting rules exactly match those already well
understood for formatting nested function calls. Examples:</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">foo</span><span class="p">({</span><span class="n">a</span><span class="p">,</span> <span class="n">b</span><span class="p">,</span> <span class="n">c</span><span class="p">},</span> <span class="p">{</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">});</span>
<span class="n">llvm</span><span class="o">::</span><span class="n">Constant</span> <span class="o">*</span><span class="n">Mask</span><span class="p">[]</span> <span class="o">=</span> <span class="p">{</span>
<span class="n">llvm</span><span class="o">::</span><span class="n">ConstantInt</span><span class="o">::</span><span class="n">get</span><span class="p">(</span><span class="n">llvm</span><span class="o">::</span><span class="n">Type</span><span class="o">::</span><span class="n">getInt32Ty</span><span class="p">(</span><span class="n">getLLVMContext</span><span class="p">()),</span> <span class="mi">0</span><span class="p">),</span>
<span class="n">llvm</span><span class="o">::</span><span class="n">ConstantInt</span><span class="o">::</span><span class="n">get</span><span class="p">(</span><span class="n">llvm</span><span class="o">::</span><span class="n">Type</span><span class="o">::</span><span class="n">getInt32Ty</span><span class="p">(</span><span class="n">getLLVMContext</span><span class="p">()),</span> <span class="mi">1</span><span class="p">),</span>
<span class="n">llvm</span><span class="o">::</span><span class="n">ConstantInt</span><span class="o">::</span><span class="n">get</span><span class="p">(</span><span class="n">llvm</span><span class="o">::</span><span class="n">Type</span><span class="o">::</span><span class="n">getInt32Ty</span><span class="p">(</span><span class="n">getLLVMContext</span><span class="p">()),</span> <span class="mi">2</span><span class="p">)};</span>
</pre></div>
</div>
<p>This formatting scheme also makes it particularly easy to get predictable,
consistent, and automatic formatting with tools like <a class="reference external" href="https://clang.llvm.org/docs/ClangFormat.html">Clang Format</a>.</p>
</div>
</div>
</div>
<div class="section" id="language-and-compiler-issues">
<h3><a class="toc-backref" href="#id21">Language and Compiler Issues</a><a class="headerlink" href="#language-and-compiler-issues" title="Permalink to this headline">¶</a></h3>
<div class="section" id="treat-compiler-warnings-like-errors">
<h4><a class="toc-backref" href="#id22">Treat Compiler Warnings Like Errors</a><a class="headerlink" href="#treat-compiler-warnings-like-errors" title="Permalink to this headline">¶</a></h4>
<p>Compiler warnings are often useful and help improve the code. Those that are
not useful, can be often suppressed with a small code change. For example, an
assignment in the <code class="docutils literal notranslate"><span class="pre">if</span></code> condition is often a typo:</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">if</span> <span class="p">(</span><span class="n">V</span> <span class="o">=</span> <span class="n">getValue</span><span class="p">())</span> <span class="p">{</span>
<span class="p">...</span>
<span class="p">}</span>
</pre></div>
</div>
<p>Several compilers will print a warning for the code above. It can be suppressed
by adding parentheses:</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">if</span> <span class="p">((</span><span class="n">V</span> <span class="o">=</span> <span class="n">getValue</span><span class="p">()))</span> <span class="p">{</span>
<span class="p">...</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
<div class="section" id="write-portable-code">
<h4><a class="toc-backref" href="#id23">Write Portable Code</a><a class="headerlink" href="#write-portable-code" title="Permalink to this headline">¶</a></h4>
<p>In almost all cases, it is possible to write completely portable code. When
you need to rely on non-portable code, put it behind a well-defined and
well-documented interface.</p>
</div>
<div class="section" id="do-not-use-rtti-or-exceptions">
<h4><a class="toc-backref" href="#id24">Do not use RTTI or Exceptions</a><a class="headerlink" href="#do-not-use-rtti-or-exceptions" title="Permalink to this headline">¶</a></h4>
<p>In an effort to reduce code and executable size, LLVM does not use exceptions
or RTTI (<a class="reference external" href="https://en.wikipedia.org/wiki/Run-time_type_information">runtime type information</a>, for example,
<code class="docutils literal notranslate"><span class="pre">dynamic_cast<></span></code>).</p>
<p>That said, LLVM does make extensive use of a hand-rolled form of RTTI that use
templates like <a class="reference internal" href="ProgrammersManual.html#isa"><span class="std std-ref">isa<>, cast<>, and dyn_cast<></span></a>.
This form of RTTI is opt-in and can be
<a class="reference internal" href="HowToSetUpLLVMStyleRTTI.html"><span class="doc">added to any class</span></a>.</p>
</div>
<div class="section" id="do-not-use-static-constructors">
<span id="static-constructor"></span><h4><a class="toc-backref" href="#id25">Do not use Static Constructors</a><a class="headerlink" href="#do-not-use-static-constructors" title="Permalink to this headline">¶</a></h4>
<p>Static constructors and destructors (e.g., global variables whose types have a
constructor or destructor) should not be added to the code base, and should be
removed wherever possible.</p>
<p>Globals in different source files are initialized in <cite>arbitrary order
<https://yosefk.com/c++fqa/ctors.html#fqa-10.12></cite>, making the code more
difficult to reason about.</p>
<p>Static constructors have negative impact on launch time of programs that use
LLVM as a library. We would really like for there to be zero cost for linking
in an additional LLVM target or other library into an application, but static
constructors undermine this goal.</p>
</div>
<div class="section" id="use-of-class-and-struct-keywords">
<h4><a class="toc-backref" href="#id26">Use of <code class="docutils literal notranslate"><span class="pre">class</span></code> and <code class="docutils literal notranslate"><span class="pre">struct</span></code> Keywords</a><a class="headerlink" href="#use-of-class-and-struct-keywords" title="Permalink to this headline">¶</a></h4>
<p>In C++, the <code class="docutils literal notranslate"><span class="pre">class</span></code> and <code class="docutils literal notranslate"><span class="pre">struct</span></code> keywords can be used almost
interchangeably. The only difference is when they are used to declare a class:
<code class="docutils literal notranslate"><span class="pre">class</span></code> makes all members private by default while <code class="docutils literal notranslate"><span class="pre">struct</span></code> makes all
members public by default.</p>
<ul class="simple">
<li><p>All declarations and definitions of a given <code class="docutils literal notranslate"><span class="pre">class</span></code> or <code class="docutils literal notranslate"><span class="pre">struct</span></code> must use
the same keyword. For example:</p></li>
</ul>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="c1">// Avoid if `Example` is defined as a struct.</span>
<span class="k">class</span> <span class="nc">Example</span><span class="p">;</span>
<span class="c1">// OK.</span>
<span class="k">struct</span> <span class="nc">Example</span><span class="p">;</span>
<span class="k">struct</span> <span class="nc">Example</span> <span class="p">{</span> <span class="p">...</span> <span class="p">};</span>
</pre></div>
</div>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">struct</span></code> should be used when <em>all</em> members are declared public.</p></li>
</ul>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="c1">// Avoid using `struct` here, use `class` instead.</span>
<span class="k">struct</span> <span class="nc">Foo</span> <span class="p">{</span>
<span class="k">private</span><span class="o">:</span>
<span class="kt">int</span> <span class="n">Data</span><span class="p">;</span>
<span class="k">public</span><span class="o">:</span>
<span class="n">Foo</span><span class="p">()</span> <span class="o">:</span> <span class="n">Data</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span> <span class="p">{</span> <span class="p">}</span>
<span class="kt">int</span> <span class="n">getData</span><span class="p">()</span> <span class="k">const</span> <span class="p">{</span> <span class="k">return</span> <span class="n">Data</span><span class="p">;</span> <span class="p">}</span>
<span class="kt">void</span> <span class="n">setData</span><span class="p">(</span><span class="kt">int</span> <span class="n">D</span><span class="p">)</span> <span class="p">{</span> <span class="n">Data</span> <span class="o">=</span> <span class="n">D</span><span class="p">;</span> <span class="p">}</span>
<span class="p">};</span>
<span class="c1">// OK to use `struct`: all members are public.</span>
<span class="k">struct</span> <span class="nc">Bar</span> <span class="p">{</span>
<span class="kt">int</span> <span class="n">Data</span><span class="p">;</span>
<span class="n">Bar</span><span class="p">()</span> <span class="o">:</span> <span class="n">Data</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span> <span class="p">{</span> <span class="p">}</span>
<span class="p">};</span>
</pre></div>
</div>
</div>
<div class="section" id="do-not-use-braced-initializer-lists-to-call-a-constructor">
<h4><a class="toc-backref" href="#id27">Do not use Braced Initializer Lists to Call a Constructor</a><a class="headerlink" href="#do-not-use-braced-initializer-lists-to-call-a-constructor" title="Permalink to this headline">¶</a></h4>
<p>Starting from C++11 there is a “generalized initialization syntax” which allows
calling constructors using braced initializer lists. Do not use these to call
constructors with non-trivial logic or if you care that you’re calling some
<em>particular</em> constructor. Those should look like function calls using
parentheses rather than like aggregate initialization. Similarly, if you need
to explicitly name the type and call its constructor to create a temporary,
don’t use a braced initializer list. Instead, use a braced initializer list
(without any type for temporaries) when doing aggregate initialization or
something notionally equivalent. Examples:</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">Foo</span> <span class="p">{</span>
<span class="k">public</span><span class="o">:</span>
<span class="c1">// Construct a Foo by reading data from the disk in the whizbang format, ...</span>
<span class="n">Foo</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">string</span> <span class="n">filename</span><span class="p">);</span>
<span class="c1">// Construct a Foo by looking up the Nth element of some global data ...</span>
<span class="n">Foo</span><span class="p">(</span><span class="kt">int</span> <span class="n">N</span><span class="p">);</span>
<span class="c1">// ...</span>
<span class="p">};</span>
<span class="c1">// The Foo constructor call is reading a file, don't use braces to call it.</span>
<span class="n">std</span><span class="o">::</span><span class="n">fill</span><span class="p">(</span><span class="n">foo</span><span class="p">.</span><span class="n">begin</span><span class="p">(),</span> <span class="n">foo</span><span class="p">.</span><span class="n">end</span><span class="p">(),</span> <span class="n">Foo</span><span class="p">(</span><span class="s">"name"</span><span class="p">));</span>
<span class="c1">// The pair is being constructed like an aggregate, use braces.</span>
<span class="n">bar_map</span><span class="p">.</span><span class="n">insert</span><span class="p">({</span><span class="n">my_key</span><span class="p">,</span> <span class="n">my_value</span><span class="p">});</span>
</pre></div>
</div>
<p>If you use a braced initializer list when initializing a variable, use an equals before the open curly brace:</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="kt">int</span> <span class="n">data</span><span class="p">[]</span> <span class="o">=</span> <span class="p">{</span><span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">};</span>
</pre></div>
</div>
</div>
<div class="section" id="use-auto-type-deduction-to-make-code-more-readable">
<h4><a class="toc-backref" href="#id28">Use <code class="docutils literal notranslate"><span class="pre">auto</span></code> Type Deduction to Make Code More Readable</a><a class="headerlink" href="#use-auto-type-deduction-to-make-code-more-readable" title="Permalink to this headline">¶</a></h4>
<p>Some are advocating a policy of “almost always <code class="docutils literal notranslate"><span class="pre">auto</span></code>” in C++11, however LLVM
uses a more moderate stance. Use <code class="docutils literal notranslate"><span class="pre">auto</span></code> if and only if it makes the code more
readable or easier to maintain. Don’t “almost always” use <code class="docutils literal notranslate"><span class="pre">auto</span></code>, but do use
<code class="docutils literal notranslate"><span class="pre">auto</span></code> with initializers like <code class="docutils literal notranslate"><span class="pre">cast<Foo>(...)</span></code> or other places where the
type is already obvious from the context. Another time when <code class="docutils literal notranslate"><span class="pre">auto</span></code> works well
for these purposes is when the type would have been abstracted away anyways,
often behind a container’s typedef such as <code class="docutils literal notranslate"><span class="pre">std::vector<T>::iterator</span></code>.</p>
<p>Similarly, C++14 adds generic lambda expressions where parameter types can be
<code class="docutils literal notranslate"><span class="pre">auto</span></code>. Use these where you would have used a template.</p>
</div>
<div class="section" id="beware-unnecessary-copies-with-auto">
<h4><a class="toc-backref" href="#id29">Beware unnecessary copies with <code class="docutils literal notranslate"><span class="pre">auto</span></code></a><a class="headerlink" href="#beware-unnecessary-copies-with-auto" title="Permalink to this headline">¶</a></h4>
<p>The convenience of <code class="docutils literal notranslate"><span class="pre">auto</span></code> makes it easy to forget that its default behavior
is a copy. Particularly in range-based <code class="docutils literal notranslate"><span class="pre">for</span></code> loops, careless copies are
expensive.</p>
<p>Use <code class="docutils literal notranslate"><span class="pre">auto</span> <span class="pre">&</span></code> for values and <code class="docutils literal notranslate"><span class="pre">auto</span> <span class="pre">*</span></code> for pointers unless you need to make a
copy.</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="c1">// Typically there's no reason to copy.</span>
<span class="k">for</span> <span class="p">(</span><span class="k">const</span> <span class="k">auto</span> <span class="o">&</span><span class="nl">Val</span> <span class="p">:</span> <span class="n">Container</span><span class="p">)</span> <span class="n">observe</span><span class="p">(</span><span class="n">Val</span><span class="p">);</span>
<span class="k">for</span> <span class="p">(</span><span class="k">auto</span> <span class="o">&</span><span class="nl">Val</span> <span class="p">:</span> <span class="n">Container</span><span class="p">)</span> <span class="n">Val</span><span class="p">.</span><span class="n">change</span><span class="p">();</span>
<span class="c1">// Remove the reference if you really want a new copy.</span>
<span class="k">for</span> <span class="p">(</span><span class="k">auto</span> <span class="nl">Val</span> <span class="p">:</span> <span class="n">Container</span><span class="p">)</span> <span class="p">{</span> <span class="n">Val</span><span class="p">.</span><span class="n">change</span><span class="p">();</span> <span class="n">saveSomewhere</span><span class="p">(</span><span class="n">Val</span><span class="p">);</span> <span class="p">}</span>
<span class="c1">// Copy pointers, but make it clear that they're pointers.</span>
<span class="k">for</span> <span class="p">(</span><span class="k">const</span> <span class="k">auto</span> <span class="o">*</span><span class="nl">Ptr</span> <span class="p">:</span> <span class="n">Container</span><span class="p">)</span> <span class="n">observe</span><span class="p">(</span><span class="o">*</span><span class="n">Ptr</span><span class="p">);</span>
<span class="k">for</span> <span class="p">(</span><span class="k">auto</span> <span class="o">*</span><span class="nl">Ptr</span> <span class="p">:</span> <span class="n">Container</span><span class="p">)</span> <span class="n">Ptr</span><span class="o">-></span><span class="n">change</span><span class="p">();</span>
</pre></div>
</div>
</div>
<div class="section" id="beware-of-non-determinism-due-to-ordering-of-pointers">
<h4><a class="toc-backref" href="#id30">Beware of non-determinism due to ordering of pointers</a><a class="headerlink" href="#beware-of-non-determinism-due-to-ordering-of-pointers" title="Permalink to this headline">¶</a></h4>
<p>In general, there is no relative ordering among pointers. As a result,
when unordered containers like sets and maps are used with pointer keys
the iteration order is undefined. Hence, iterating such containers may
result in non-deterministic code generation. While the generated code
might work correctly, non-determinism can make it harder to reproduce bugs and
debug the compiler.</p>
<p>In case an ordered result is expected, remember to
sort an unordered container before iteration. Or use ordered containers
like <code class="docutils literal notranslate"><span class="pre">vector</span></code>/<code class="docutils literal notranslate"><span class="pre">MapVector</span></code>/<code class="docutils literal notranslate"><span class="pre">SetVector</span></code> if you want to iterate pointer
keys.</p>
</div>
<div class="section" id="beware-of-non-deterministic-sorting-order-of-equal-elements">
<h4><a class="toc-backref" href="#id31">Beware of non-deterministic sorting order of equal elements</a><a class="headerlink" href="#beware-of-non-deterministic-sorting-order-of-equal-elements" title="Permalink to this headline">¶</a></h4>
<p><code class="docutils literal notranslate"><span class="pre">std::sort</span></code> uses a non-stable sorting algorithm in which the order of equal
elements is not guaranteed to be preserved. Thus using <code class="docutils literal notranslate"><span class="pre">std::sort</span></code> for a
container having equal elements may result in non-deterministic behavior.
To uncover such instances of non-determinism, LLVM has introduced a new
llvm::sort wrapper function. For an EXPENSIVE_CHECKS build this will randomly
shuffle the container before sorting. Default to using <code class="docutils literal notranslate"><span class="pre">llvm::sort</span></code> instead
of <code class="docutils literal notranslate"><span class="pre">std::sort</span></code>.</p>
</div>
</div>
</div>
<div class="section" id="style-issues">
<h2><a class="toc-backref" href="#id32">Style Issues</a><a class="headerlink" href="#style-issues" title="Permalink to this headline">¶</a></h2>
<div class="section" id="the-high-level-issues">
<h3><a class="toc-backref" href="#id33">The High-Level Issues</a><a class="headerlink" href="#the-high-level-issues" title="Permalink to this headline">¶</a></h3>
<div class="section" id="self-contained-headers">
<h4><a class="toc-backref" href="#id34">Self-contained Headers</a><a class="headerlink" href="#self-contained-headers" title="Permalink to this headline">¶</a></h4>
<p>Header files should be self-contained (compile on their own) and end in <code class="docutils literal notranslate"><span class="pre">.h</span></code>.
Non-header files that are meant for inclusion should end in <code class="docutils literal notranslate"><span class="pre">.inc</span></code> and be
used sparingly.</p>
<p>All header files should be self-contained. Users and refactoring tools should
not have to adhere to special conditions to include the header. Specifically, a
header should have header guards and include all other headers it needs.</p>
<p>There are rare cases where a file designed to be included is not
self-contained. These are typically intended to be included at unusual
locations, such as the middle of another file. They might not use header
guards, and might not include their prerequisites. Name such files with the
.inc extension. Use sparingly, and prefer self-contained headers when possible.</p>
<p>In general, a header should be implemented by one or more <code class="docutils literal notranslate"><span class="pre">.cpp</span></code> files. Each
of these <code class="docutils literal notranslate"><span class="pre">.cpp</span></code> files should include the header that defines their interface
first. This ensures that all of the dependences of the header have been
properly added to the header itself, and are not implicit. System headers
should be included after user headers for a translation unit.</p>
</div>
<div class="section" id="library-layering">
<h4><a class="toc-backref" href="#id35">Library Layering</a><a class="headerlink" href="#library-layering" title="Permalink to this headline">¶</a></h4>
<p>A directory of header files (for example <code class="docutils literal notranslate"><span class="pre">include/llvm/Foo</span></code>) defines a
library (<code class="docutils literal notranslate"><span class="pre">Foo</span></code>). One library (both
its headers and implementation) should only use things from the libraries
listed in its dependencies.</p>
<p>Some of this constraint can be enforced by classic Unix linkers (Mac & Windows
linkers, as well as lld, do not enforce this constraint). A Unix linker
searches left to right through the libraries specified on its command line and
never revisits a library. In this way, no circular dependencies between
libraries can exist.</p>
<p>This doesn’t fully enforce all inter-library dependencies, and importantly
doesn’t enforce header file circular dependencies created by inline functions.
A good way to answer the “is this layered correctly” would be to consider
whether a Unix linker would succeed at linking the program if all inline
functions were defined out-of-line. (& for all valid orderings of dependencies
- since linking resolution is linear, it’s possible that some implicit
dependencies can sneak through: A depends on B and C, so valid orderings are
“C B A” or “B C A”, in both cases the explicit dependencies come before their
use. But in the first case, B could still link successfully if it implicitly
depended on C, or the opposite in the second case)</p>
</div>
<div class="section" id="include-as-little-as-possible">
<span id="minimal-list-of-includes"></span><h4><a class="toc-backref" href="#id36"><code class="docutils literal notranslate"><span class="pre">#include</span></code> as Little as Possible</a><a class="headerlink" href="#include-as-little-as-possible" title="Permalink to this headline">¶</a></h4>
<p><code class="docutils literal notranslate"><span class="pre">#include</span></code> hurts compile time performance. Don’t do it unless you have to,
especially in header files.</p>
<p>But wait! Sometimes you need to have the definition of a class to use it, or to
inherit from it. In these cases go ahead and <code class="docutils literal notranslate"><span class="pre">#include</span></code> that header file. Be
aware however that there are many cases where you don’t need to have the full
definition of a class. If you are using a pointer or reference to a class, you
don’t need the header file. If you are simply returning a class instance from a
prototyped function or method, you don’t need it. In fact, for most cases, you
simply don’t need the definition of a class. And not <code class="docutils literal notranslate"><span class="pre">#include</span></code>ing speeds up
compilation.</p>
<p>It is easy to try to go too overboard on this recommendation, however. You
<strong>must</strong> include all of the header files that you are using — you can include
them either directly or indirectly through another header file. To make sure
that you don’t accidentally forget to include a header file in your module
header, make sure to include your module header <strong>first</strong> in the implementation
file (as mentioned above). This way there won’t be any hidden dependencies that
you’ll find out about later.</p>
</div>
<div class="section" id="keep-internal-headers-private">
<h4><a class="toc-backref" href="#id37">Keep “Internal” Headers Private</a><a class="headerlink" href="#keep-internal-headers-private" title="Permalink to this headline">¶</a></h4>
<p>Many modules have a complex implementation that causes them to use more than one
implementation (<code class="docutils literal notranslate"><span class="pre">.cpp</span></code>) file. It is often tempting to put the internal
communication interface (helper classes, extra functions, etc) in the public
module header file. Don’t do this!</p>
<p>If you really need to do something like this, put a private header file in the
same directory as the source files, and include it locally. This ensures that
your private interface remains private and undisturbed by outsiders.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>It’s okay to put extra implementation methods in a public class itself. Just
make them private (or protected) and all is well.</p>
</div>
</div>
<div class="section" id="use-namespace-qualifiers-to-implement-previously-declared-functions">
<h4><a class="toc-backref" href="#id38">Use Namespace Qualifiers to Implement Previously Declared Functions</a><a class="headerlink" href="#use-namespace-qualifiers-to-implement-previously-declared-functions" title="Permalink to this headline">¶</a></h4>
<p>When providing an out of line implementation of a function in a source file, do
not open namespace blocks in the source file. Instead, use namespace qualifiers
to help ensure that your definition matches an existing declaration. Do this:</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="c1">// Foo.h</span>
<span class="k">namespace</span> <span class="n">llvm</span> <span class="p">{</span>
<span class="kt">int</span> <span class="nf">foo</span><span class="p">(</span><span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">s</span><span class="p">);</span>
<span class="p">}</span>
<span class="c1">// Foo.cpp</span>
<span class="cp">#include</span> <span class="cpf">"Foo.h"</span><span class="cp"></span>
<span class="k">using</span> <span class="k">namespace</span> <span class="n">llvm</span><span class="p">;</span>
<span class="kt">int</span> <span class="n">llvm</span><span class="o">::</span><span class="n">foo</span><span class="p">(</span><span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">s</span><span class="p">)</span> <span class="p">{</span>
<span class="c1">// ...</span>
<span class="p">}</span>
</pre></div>
</div>
<p>Doing this helps to avoid bugs where the definition does not match the
declaration from the header. For example, the following C++ code defines a new
overload of <code class="docutils literal notranslate"><span class="pre">llvm::foo</span></code> instead of providing a definition for the existing
function declared in the header:</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="c1">// Foo.cpp</span>
<span class="cp">#include</span> <span class="cpf">"Foo.h"</span><span class="cp"></span>
<span class="k">namespace</span> <span class="n">llvm</span> <span class="p">{</span>
<span class="kt">int</span> <span class="nf">foo</span><span class="p">(</span><span class="kt">char</span> <span class="o">*</span><span class="n">s</span><span class="p">)</span> <span class="p">{</span> <span class="c1">// Mismatch between "const char *" and "char *"</span>
<span class="p">}</span>
<span class="p">}</span> <span class="c1">// end namespace llvm</span>
</pre></div>
</div>
<p>This error will not be caught until the build is nearly complete, when the
linker fails to find a definition for any uses of the original function. If the
function were instead defined with a namespace qualifier, the error would have
been caught immediately when the definition was compiled.</p>
<p>Class method implementations must already name the class and new overloads
cannot be introduced out of line, so this recommendation does not apply to them.</p>
</div>
<div class="section" id="use-early-exits-and-continue-to-simplify-code">
<span id="early-exits"></span><h4><a class="toc-backref" href="#id39">Use Early Exits and <code class="docutils literal notranslate"><span class="pre">continue</span></code> to Simplify Code</a><a class="headerlink" href="#use-early-exits-and-continue-to-simplify-code" title="Permalink to this headline">¶</a></h4>
<p>When reading code, keep in mind how much state and how many previous decisions
have to be remembered by the reader to understand a block of code. Aim to
reduce indentation where possible when it doesn’t make it more difficult to
understand the code. One great way to do this is by making use of early exits
and the <code class="docutils literal notranslate"><span class="pre">continue</span></code> keyword in long loops. Consider this code that does not
use an early exit:</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">Value</span> <span class="o">*</span><span class="nf">doSomething</span><span class="p">(</span><span class="n">Instruction</span> <span class="o">*</span><span class="n">I</span><span class="p">)</span> <span class="p">{</span>
<span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="n">I</span><span class="o">-></span><span class="n">isTerminator</span><span class="p">()</span> <span class="o">&&</span>
<span class="n">I</span><span class="o">-></span><span class="n">hasOneUse</span><span class="p">()</span> <span class="o">&&</span> <span class="n">doOtherThing</span><span class="p">(</span><span class="n">I</span><span class="p">))</span> <span class="p">{</span>
<span class="p">...</span> <span class="n">some</span> <span class="kt">long</span> <span class="n">code</span> <span class="p">....</span>
<span class="p">}</span>
<span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
<span class="p">}</span>
</pre></div>
</div>
<p>This code has several problems if the body of the <code class="docutils literal notranslate"><span class="pre">'if'</span></code> is large. When
you’re looking at the top of the function, it isn’t immediately clear that this
<em>only</em> does interesting things with non-terminator instructions, and only
applies to things with the other predicates. Second, it is relatively difficult
to describe (in comments) why these predicates are important because the <code class="docutils literal notranslate"><span class="pre">if</span></code>
statement makes it difficult to lay out the comments. Third, when you’re deep
within the body of the code, it is indented an extra level. Finally, when
reading the top of the function, it isn’t clear what the result is if the
predicate isn’t true; you have to read to the end of the function to know that
it returns null.</p>
<p>It is much preferred to format the code like this:</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">Value</span> <span class="o">*</span><span class="nf">doSomething</span><span class="p">(</span><span class="n">Instruction</span> <span class="o">*</span><span class="n">I</span><span class="p">)</span> <span class="p">{</span>
<span class="c1">// Terminators never need 'something' done to them because ...</span>
<span class="k">if</span> <span class="p">(</span><span class="n">I</span><span class="o">-></span><span class="n">isTerminator</span><span class="p">())</span>
<span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
<span class="c1">// We conservatively avoid transforming instructions with multiple uses</span>
<span class="c1">// because goats like cheese.</span>
<span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="n">I</span><span class="o">-></span><span class="n">hasOneUse</span><span class="p">())</span>
<span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
<span class="c1">// This is really just here for example.</span>
<span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="n">doOtherThing</span><span class="p">(</span><span class="n">I</span><span class="p">))</span>
<span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
<span class="p">...</span> <span class="n">some</span> <span class="kt">long</span> <span class="n">code</span> <span class="p">....</span>
<span class="p">}</span>
</pre></div>
</div>
<p>This fixes these problems. A similar problem frequently happens in <code class="docutils literal notranslate"><span class="pre">for</span></code>
loops. A silly example is something like this:</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">for</span> <span class="p">(</span><span class="n">Instruction</span> <span class="o">&</span><span class="nl">I</span> <span class="p">:</span> <span class="n">BB</span><span class="p">)</span> <span class="p">{</span>
<span class="k">if</span> <span class="p">(</span><span class="k">auto</span> <span class="o">*</span><span class="n">BO</span> <span class="o">=</span> <span class="n">dyn_cast</span><span class="o"><</span><span class="n">BinaryOperator</span><span class="o">></span><span class="p">(</span><span class="o">&</span><span class="n">I</span><span class="p">))</span> <span class="p">{</span>
<span class="n">Value</span> <span class="o">*</span><span class="n">LHS</span> <span class="o">=</span> <span class="n">BO</span><span class="o">-></span><span class="n">getOperand</span><span class="p">(</span><span class="mi">0</span><span class="p">);</span>
<span class="n">Value</span> <span class="o">*</span><span class="n">RHS</span> <span class="o">=</span> <span class="n">BO</span><span class="o">-></span><span class="n">getOperand</span><span class="p">(</span><span class="mi">1</span><span class="p">);</span>
<span class="k">if</span> <span class="p">(</span><span class="n">LHS</span> <span class="o">!=</span> <span class="n">RHS</span><span class="p">)</span> <span class="p">{</span>
<span class="p">...</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="p">}</span>
</pre></div>
</div>
<p>When you have very, very small loops, this sort of structure is fine. But if it
exceeds more than 10-15 lines, it becomes difficult for people to read and
understand at a glance. The problem with this sort of code is that it gets very
nested very quickly. Meaning that the reader of the code has to keep a lot of
context in their brain to remember what is going immediately on in the loop,
because they don’t know if/when the <code class="docutils literal notranslate"><span class="pre">if</span></code> conditions will have <code class="docutils literal notranslate"><span class="pre">else</span></code>s etc.
It is strongly preferred to structure the loop like this:</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">for</span> <span class="p">(</span><span class="n">Instruction</span> <span class="o">&</span><span class="nl">I</span> <span class="p">:</span> <span class="n">BB</span><span class="p">)</span> <span class="p">{</span>
<span class="k">auto</span> <span class="o">*</span><span class="n">BO</span> <span class="o">=</span> <span class="n">dyn_cast</span><span class="o"><</span><span class="n">BinaryOperator</span><span class="o">></span><span class="p">(</span><span class="o">&</span><span class="n">I</span><span class="p">);</span>
<span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="n">BO</span><span class="p">)</span> <span class="k">continue</span><span class="p">;</span>
<span class="n">Value</span> <span class="o">*</span><span class="n">LHS</span> <span class="o">=</span> <span class="n">BO</span><span class="o">-></span><span class="n">getOperand</span><span class="p">(</span><span class="mi">0</span><span class="p">);</span>
<span class="n">Value</span> <span class="o">*</span><span class="n">RHS</span> <span class="o">=</span> <span class="n">BO</span><span class="o">-></span><span class="n">getOperand</span><span class="p">(</span><span class="mi">1</span><span class="p">);</span>
<span class="k">if</span> <span class="p">(</span><span class="n">LHS</span> <span class="o">==</span> <span class="n">RHS</span><span class="p">)</span> <span class="k">continue</span><span class="p">;</span>
<span class="p">...</span>
<span class="p">}</span>
</pre></div>
</div>
<p>This has all the benefits of using early exits for functions: it reduces nesting
of the loop, it makes it easier to describe why the conditions are true, and it
makes it obvious to the reader that there is no <code class="docutils literal notranslate"><span class="pre">else</span></code> coming up that they
have to push context into their brain for. If a loop is large, this can be a
big understandability win.</p>
</div>
<div class="section" id="don-t-use-else-after-a-return">
<h4><a class="toc-backref" href="#id40">Don’t use <code class="docutils literal notranslate"><span class="pre">else</span></code> after a <code class="docutils literal notranslate"><span class="pre">return</span></code></a><a class="headerlink" href="#don-t-use-else-after-a-return" title="Permalink to this headline">¶</a></h4>
<p>For similar reasons as above (reduction of indentation and easier reading), please
do not use <code class="docutils literal notranslate"><span class="pre">'else'</span></code> or <code class="docutils literal notranslate"><span class="pre">'else</span> <span class="pre">if'</span></code> after something that interrupts control
flow — like <code class="docutils literal notranslate"><span class="pre">return</span></code>, <code class="docutils literal notranslate"><span class="pre">break</span></code>, <code class="docutils literal notranslate"><span class="pre">continue</span></code>, <code class="docutils literal notranslate"><span class="pre">goto</span></code>, etc. For example:</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">case</span> <span class="sc">'J'</span><span class="o">:</span> <span class="p">{</span>
<span class="k">if</span> <span class="p">(</span><span class="n">Signed</span><span class="p">)</span> <span class="p">{</span>
<span class="n">Type</span> <span class="o">=</span> <span class="n">Context</span><span class="p">.</span><span class="n">getsigjmp_bufType</span><span class="p">();</span>
<span class="k">if</span> <span class="p">(</span><span class="n">Type</span><span class="p">.</span><span class="n">isNull</span><span class="p">())</span> <span class="p">{</span>
<span class="n">Error</span> <span class="o">=</span> <span class="n">ASTContext</span><span class="o">::</span><span class="n">GE_Missing_sigjmp_buf</span><span class="p">;</span>
<span class="k">return</span> <span class="nf">QualType</span><span class="p">();</span>
<span class="p">}</span> <span class="k">else</span> <span class="p">{</span>
<span class="k">break</span><span class="p">;</span> <span class="c1">// Unnecessary.</span>
<span class="p">}</span>
<span class="p">}</span> <span class="k">else</span> <span class="p">{</span>
<span class="n">Type</span> <span class="o">=</span> <span class="n">Context</span><span class="p">.</span><span class="n">getjmp_bufType</span><span class="p">();</span>
<span class="k">if</span> <span class="p">(</span><span class="n">Type</span><span class="p">.</span><span class="n">isNull</span><span class="p">())</span> <span class="p">{</span>
<span class="n">Error</span> <span class="o">=</span> <span class="n">ASTContext</span><span class="o">::</span><span class="n">GE_Missing_jmp_buf</span><span class="p">;</span>
<span class="k">return</span> <span class="nf">QualType</span><span class="p">();</span>
<span class="p">}</span> <span class="k">else</span> <span class="p">{</span>
<span class="k">break</span><span class="p">;</span> <span class="c1">// Unnecessary.</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="p">}</span>
</pre></div>
</div>
<p>It is better to write it like this:</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">case</span> <span class="sc">'J'</span><span class="o">:</span>
<span class="k">if</span> <span class="p">(</span><span class="n">Signed</span><span class="p">)</span> <span class="p">{</span>
<span class="n">Type</span> <span class="o">=</span> <span class="n">Context</span><span class="p">.</span><span class="n">getsigjmp_bufType</span><span class="p">();</span>
<span class="k">if</span> <span class="p">(</span><span class="n">Type</span><span class="p">.</span><span class="n">isNull</span><span class="p">())</span> <span class="p">{</span>
<span class="n">Error</span> <span class="o">=</span> <span class="n">ASTContext</span><span class="o">::</span><span class="n">GE_Missing_sigjmp_buf</span><span class="p">;</span>
<span class="k">return</span> <span class="nf">QualType</span><span class="p">();</span>
<span class="p">}</span>
<span class="p">}</span> <span class="k">else</span> <span class="p">{</span>
<span class="n">Type</span> <span class="o">=</span> <span class="n">Context</span><span class="p">.</span><span class="n">getjmp_bufType</span><span class="p">();</span>
<span class="k">if</span> <span class="p">(</span><span class="n">Type</span><span class="p">.</span><span class="n">isNull</span><span class="p">())</span> <span class="p">{</span>
<span class="n">Error</span> <span class="o">=</span> <span class="n">ASTContext</span><span class="o">::</span><span class="n">GE_Missing_jmp_buf</span><span class="p">;</span>
<span class="k">return</span> <span class="nf">QualType</span><span class="p">();</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="k">break</span><span class="p">;</span>
</pre></div>
</div>
<p>Or better yet (in this case) as:</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">case</span> <span class="sc">'J'</span><span class="o">:</span>
<span class="k">if</span> <span class="p">(</span><span class="n">Signed</span><span class="p">)</span>
<span class="n">Type</span> <span class="o">=</span> <span class="n">Context</span><span class="p">.</span><span class="n">getsigjmp_bufType</span><span class="p">();</span>
<span class="k">else</span>
<span class="n">Type</span> <span class="o">=</span> <span class="n">Context</span><span class="p">.</span><span class="n">getjmp_bufType</span><span class="p">();</span>
<span class="k">if</span> <span class="p">(</span><span class="n">Type</span><span class="p">.</span><span class="n">isNull</span><span class="p">())</span> <span class="p">{</span>
<span class="n">Error</span> <span class="o">=</span> <span class="n">Signed</span> <span class="o">?</span> <span class="n">ASTContext</span><span class="o">::</span><span class="nl">GE_Missing_sigjmp_buf</span> <span class="p">:</span>
<span class="n">ASTContext</span><span class="o">::</span><span class="n">GE_Missing_jmp_buf</span><span class="p">;</span>
<span class="k">return</span> <span class="nf">QualType</span><span class="p">();</span>
<span class="p">}</span>
<span class="k">break</span><span class="p">;</span>
</pre></div>
</div>
<p>The idea is to reduce indentation and the amount of code you have to keep track
of when reading the code.</p>
</div>
<div class="section" id="turn-predicate-loops-into-predicate-functions">
<h4><a class="toc-backref" href="#id41">Turn Predicate Loops into Predicate Functions</a><a class="headerlink" href="#turn-predicate-loops-into-predicate-functions" title="Permalink to this headline">¶</a></h4>
<p>It is very common to write small loops that just compute a boolean value. There
are a number of ways that people commonly write these, but an example of this
sort of thing is:</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="kt">bool</span> <span class="n">FoundFoo</span> <span class="o">=</span> <span class="nb">false</span><span class="p">;</span>
<span class="k">for</span> <span class="p">(</span><span class="kt">unsigned</span> <span class="n">I</span> <span class="o">=</span> <span class="mi">0</span><span class="p">,</span> <span class="n">E</span> <span class="o">=</span> <span class="n">BarList</span><span class="p">.</span><span class="n">size</span><span class="p">();</span> <span class="n">I</span> <span class="o">!=</span> <span class="n">E</span><span class="p">;</span> <span class="o">++</span><span class="n">I</span><span class="p">)</span>
<span class="k">if</span> <span class="p">(</span><span class="n">BarList</span><span class="p">[</span><span class="n">I</span><span class="p">]</span><span class="o">-></span><span class="n">isFoo</span><span class="p">())</span> <span class="p">{</span>
<span class="n">FoundFoo</span> <span class="o">=</span> <span class="nb">true</span><span class="p">;</span>
<span class="k">break</span><span class="p">;</span>
<span class="p">}</span>
<span class="k">if</span> <span class="p">(</span><span class="n">FoundFoo</span><span class="p">)</span> <span class="p">{</span>
<span class="p">...</span>
<span class="p">}</span>
</pre></div>
</div>
<p>Instead of this sort of loop, we prefer to use a predicate function (which may
be <a class="reference internal" href="#static">static</a>) that uses <a class="reference internal" href="#early-exits">early exits</a>:</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="c1">/// \returns true if the specified list has an element that is a foo.</span>
<span class="k">static</span> <span class="kt">bool</span> <span class="n">containsFoo</span><span class="p">(</span><span class="k">const</span> <span class="n">std</span><span class="o">::</span><span class="n">vector</span><span class="o"><</span><span class="n">Bar</span><span class="o">*></span> <span class="o">&</span><span class="n">List</span><span class="p">)</span> <span class="p">{</span>
<span class="k">for</span> <span class="p">(</span><span class="kt">unsigned</span> <span class="n">I</span> <span class="o">=</span> <span class="mi">0</span><span class="p">,</span> <span class="n">E</span> <span class="o">=</span> <span class="n">List</span><span class="p">.</span><span class="n">size</span><span class="p">();</span> <span class="n">I</span> <span class="o">!=</span> <span class="n">E</span><span class="p">;</span> <span class="o">++</span><span class="n">I</span><span class="p">)</span>
<span class="k">if</span> <span class="p">(</span><span class="n">List</span><span class="p">[</span><span class="n">I</span><span class="p">]</span><span class="o">-></span><span class="n">isFoo</span><span class="p">())</span>
<span class="k">return</span> <span class="nb">true</span><span class="p">;</span>
<span class="k">return</span> <span class="nb">false</span><span class="p">;</span>
<span class="p">}</span>
<span class="p">...</span>
<span class="k">if</span> <span class="p">(</span><span class="n">containsFoo</span><span class="p">(</span><span class="n">BarList</span><span class="p">))</span> <span class="p">{</span>
<span class="p">...</span>
<span class="p">}</span>
</pre></div>
</div>
<p>There are many reasons for doing this: it reduces indentation and factors out
code which can often be shared by other code that checks for the same predicate.
More importantly, it <em>forces you to pick a name</em> for the function, and forces
you to write a comment for it. In this silly example, this doesn’t add much
value. However, if the condition is complex, this can make it a lot easier for
the reader to understand the code that queries for this predicate. Instead of
being faced with the in-line details of how we check to see if the BarList
contains a foo, we can trust the function name and continue reading with better
locality.</p>
</div>
</div>
<div class="section" id="the-low-level-issues">
<h3><a class="toc-backref" href="#id42">The Low-Level Issues</a><a class="headerlink" href="#the-low-level-issues" title="Permalink to this headline">¶</a></h3>
<div class="section" id="name-types-functions-variables-and-enumerators-properly">
<h4><a class="toc-backref" href="#id43">Name Types, Functions, Variables, and Enumerators Properly</a><a class="headerlink" href="#name-types-functions-variables-and-enumerators-properly" title="Permalink to this headline">¶</a></h4>
<p>Poorly-chosen names can mislead the reader and cause bugs. We cannot stress
enough how important it is to use <em>descriptive</em> names. Pick names that match
the semantics and role of the underlying entities, within reason. Avoid
abbreviations unless they are well known. After picking a good name, make sure
to use consistent capitalization for the name, as inconsistency requires clients
to either memorize the APIs or to look it up to find the exact spelling.</p>
<p>In general, names should be in camel case (e.g. <code class="docutils literal notranslate"><span class="pre">TextFileReader</span></code> and
<code class="docutils literal notranslate"><span class="pre">isLValue()</span></code>). Different kinds of declarations have different rules:</p>
<ul>
<li><p><strong>Type names</strong> (including classes, structs, enums, typedefs, etc) should be
nouns and start with an upper-case letter (e.g. <code class="docutils literal notranslate"><span class="pre">TextFileReader</span></code>).</p></li>
<li><p><strong>Variable names</strong> should be nouns (as they represent state). The name should
be camel case, and start with an upper case letter (e.g. <code class="docutils literal notranslate"><span class="pre">Leader</span></code> or
<code class="docutils literal notranslate"><span class="pre">Boats</span></code>).</p></li>
<li><p><strong>Function names</strong> should be verb phrases (as they represent actions), and
command-like function should be imperative. The name should be camel case,
and start with a lower case letter (e.g. <code class="docutils literal notranslate"><span class="pre">openFile()</span></code> or <code class="docutils literal notranslate"><span class="pre">isFoo()</span></code>).</p></li>
<li><p><strong>Enum declarations</strong> (e.g. <code class="docutils literal notranslate"><span class="pre">enum</span> <span class="pre">Foo</span> <span class="pre">{...}</span></code>) are types, so they should
follow the naming conventions for types. A common use for enums is as a
discriminator for a union, or an indicator of a subclass. When an enum is
used for something like this, it should have a <code class="docutils literal notranslate"><span class="pre">Kind</span></code> suffix
(e.g. <code class="docutils literal notranslate"><span class="pre">ValueKind</span></code>).</p></li>
<li><p><strong>Enumerators</strong> (e.g. <code class="docutils literal notranslate"><span class="pre">enum</span> <span class="pre">{</span> <span class="pre">Foo,</span> <span class="pre">Bar</span> <span class="pre">}</span></code>) and <strong>public member variables</strong>
should start with an upper-case letter, just like types. Unless the
enumerators are defined in their own small namespace or inside a class,
enumerators should have a prefix corresponding to the enum declaration name.
For example, <code class="docutils literal notranslate"><span class="pre">enum</span> <span class="pre">ValueKind</span> <span class="pre">{</span> <span class="pre">...</span> <span class="pre">};</span></code> may contain enumerators like
<code class="docutils literal notranslate"><span class="pre">VK_Argument</span></code>, <code class="docutils literal notranslate"><span class="pre">VK_BasicBlock</span></code>, etc. Enumerators that are just
convenience constants are exempt from the requirement for a prefix. For
instance:</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">enum</span> <span class="p">{</span>
<span class="n">MaxSize</span> <span class="o">=</span> <span class="mi">42</span><span class="p">,</span>
<span class="n">Density</span> <span class="o">=</span> <span class="mi">12</span>
<span class="p">};</span>
</pre></div>
</div>
</li>
</ul>
<p>As an exception, classes that mimic STL classes can have member names in STL’s
style of lower-case words separated by underscores (e.g. <code class="docutils literal notranslate"><span class="pre">begin()</span></code>,
<code class="docutils literal notranslate"><span class="pre">push_back()</span></code>, and <code class="docutils literal notranslate"><span class="pre">empty()</span></code>). Classes that provide multiple
iterators should add a singular prefix to <code class="docutils literal notranslate"><span class="pre">begin()</span></code> and <code class="docutils literal notranslate"><span class="pre">end()</span></code>
(e.g. <code class="docutils literal notranslate"><span class="pre">global_begin()</span></code> and <code class="docutils literal notranslate"><span class="pre">use_begin()</span></code>).</p>
<p>Here are some examples:</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">VehicleMaker</span> <span class="p">{</span>
<span class="p">...</span>
<span class="n">Factory</span><span class="o"><</span><span class="n">Tire</span><span class="o">></span> <span class="n">F</span><span class="p">;</span> <span class="c1">// Avoid: a non-descriptive abbreviation.</span>
<span class="n">Factory</span><span class="o"><</span><span class="n">Tire</span><span class="o">></span> <span class="n">Factory</span><span class="p">;</span> <span class="c1">// Better: more descriptive.</span>
<span class="n">Factory</span><span class="o"><</span><span class="n">Tire</span><span class="o">></span> <span class="n">TireFactory</span><span class="p">;</span> <span class="c1">// Even better: if VehicleMaker has more than one</span>
<span class="c1">// kind of factories.</span>
<span class="p">};</span>
<span class="n">Vehicle</span> <span class="nf">makeVehicle</span><span class="p">(</span><span class="n">VehicleType</span> <span class="n">Type</span><span class="p">)</span> <span class="p">{</span>
<span class="n">VehicleMaker</span> <span class="n">M</span><span class="p">;</span> <span class="c1">// Might be OK if scope is small.</span>
<span class="n">Tire</span> <span class="n">Tmp1</span> <span class="o">=</span> <span class="n">M</span><span class="p">.</span><span class="n">makeTire</span><span class="p">();</span> <span class="c1">// Avoid: 'Tmp1' provides no information.</span>
<span class="n">Light</span> <span class="n">Headlight</span> <span class="o">=</span> <span class="n">M</span><span class="p">.</span><span class="n">makeLight</span><span class="p">(</span><span class="s">"head"</span><span class="p">);</span> <span class="c1">// Good: descriptive.</span>
<span class="p">...</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
<div class="section" id="assert-liberally">
<h4><a class="toc-backref" href="#id44">Assert Liberally</a><a class="headerlink" href="#assert-liberally" title="Permalink to this headline">¶</a></h4>
<p>Use the “<code class="docutils literal notranslate"><span class="pre">assert</span></code>” macro to its fullest. Check all of your preconditions and
assumptions, you never know when a bug (not necessarily even yours) might be
caught early by an assertion, which reduces debugging time dramatically. The
“<code class="docutils literal notranslate"><span class="pre"><cassert></span></code>” header file is probably already included by the header files you
are using, so it doesn’t cost anything to use it.</p>
<p>To further assist with debugging, make sure to put some kind of error message in
the assertion statement, which is printed if the assertion is tripped. This
helps the poor debugger make sense of why an assertion is being made and
enforced, and hopefully what to do about it. Here is one complete example:</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="kr">inline</span> <span class="n">Value</span> <span class="o">*</span><span class="n">getOperand</span><span class="p">(</span><span class="kt">unsigned</span> <span class="n">I</span><span class="p">)</span> <span class="p">{</span>
<span class="n">assert</span><span class="p">(</span><span class="n">I</span> <span class="o"><</span> <span class="n">Operands</span><span class="p">.</span><span class="n">size</span><span class="p">()</span> <span class="o">&&</span> <span class="s">"getOperand() out of range!"</span><span class="p">);</span>
<span class="k">return</span> <span class="n">Operands</span><span class="p">[</span><span class="n">I</span><span class="p">];</span>
<span class="p">}</span>
</pre></div>
</div>
<p>Here are more examples:</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">assert</span><span class="p">(</span><span class="n">Ty</span><span class="o">-></span><span class="n">isPointerType</span><span class="p">()</span> <span class="o">&&</span> <span class="s">"Can't allocate a non-pointer type!"</span><span class="p">);</span>
<span class="n">assert</span><span class="p">((</span><span class="n">Opcode</span> <span class="o">==</span> <span class="n">Shl</span> <span class="o">||</span> <span class="n">Opcode</span> <span class="o">==</span> <span class="n">Shr</span><span class="p">)</span> <span class="o">&&</span> <span class="s">"ShiftInst Opcode invalid!"</span><span class="p">);</span>
<span class="n">assert</span><span class="p">(</span><span class="n">idx</span> <span class="o"><</span> <span class="n">getNumSuccessors</span><span class="p">()</span> <span class="o">&&</span> <span class="s">"Successor # out of range!"</span><span class="p">);</span>
<span class="n">assert</span><span class="p">(</span><span class="n">V1</span><span class="p">.</span><span class="n">getType</span><span class="p">()</span> <span class="o">==</span> <span class="n">V2</span><span class="p">.</span><span class="n">getType</span><span class="p">()</span> <span class="o">&&</span> <span class="s">"Constant types must be identical!"</span><span class="p">);</span>
<span class="n">assert</span><span class="p">(</span><span class="n">isa</span><span class="o"><</span><span class="n">PHINode</span><span class="o">></span><span class="p">(</span><span class="n">Succ</span><span class="o">-></span><span class="n">front</span><span class="p">())</span> <span class="o">&&</span> <span class="s">"Only works on PHId BBs!"</span><span class="p">);</span>
</pre></div>
</div>
<p>You get the idea.</p>
<p>In the past, asserts were used to indicate a piece of code that should not be
reached. These were typically of the form:</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">assert</span><span class="p">(</span><span class="mi">0</span> <span class="o">&&</span> <span class="s">"Invalid radix for integer literal"</span><span class="p">);</span>
</pre></div>
</div>
<p>This has a few issues, the main one being that some compilers might not
understand the assertion, or warn about a missing return in builds where
assertions are compiled out.</p>
<p>Today, we have something much better: <code class="docutils literal notranslate"><span class="pre">llvm_unreachable</span></code>:</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">llvm_unreachable</span><span class="p">(</span><span class="s">"Invalid radix for integer literal"</span><span class="p">);</span>
</pre></div>
</div>
<p>When assertions are enabled, this will print the message if it’s ever reached
and then exit the program. When assertions are disabled (i.e. in release
builds), <code class="docutils literal notranslate"><span class="pre">llvm_unreachable</span></code> becomes a hint to compilers to skip generating
code for this branch. If the compiler does not support this, it will fall back
to the “abort” implementation.</p>
<p>Use <code class="docutils literal notranslate"><span class="pre">llvm_unreachable</span></code> to mark a specific point in code that should never be
reached. This is especially desirable for addressing warnings about unreachable
branches, etc., but can be used whenever reaching a particular code path is
unconditionally a bug (not originating from user input; see below) of some kind.
Use of <code class="docutils literal notranslate"><span class="pre">assert</span></code> should always include a testable predicate (as opposed to
<code class="docutils literal notranslate"><span class="pre">assert(false)</span></code>).</p>
<p>If the error condition can be triggered by user input then the
recoverable error mechanism described in <a class="reference internal" href="ProgrammersManual.html"><span class="doc">LLVM Programmer’s Manual</span></a> should be
used instead. In cases where this is not practical, <code class="docutils literal notranslate"><span class="pre">report_fatal_error</span></code> may
be used.</p>
<p>Another issue is that values used only by assertions will produce an “unused
value” warning when assertions are disabled. For example, this code will warn:</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="kt">unsigned</span> <span class="n">Size</span> <span class="o">=</span> <span class="n">V</span><span class="p">.</span><span class="n">size</span><span class="p">();</span>
<span class="n">assert</span><span class="p">(</span><span class="n">Size</span> <span class="o">></span> <span class="mi">42</span> <span class="o">&&</span> <span class="s">"Vector smaller than it should be"</span><span class="p">);</span>
<span class="kt">bool</span> <span class="n">NewToSet</span> <span class="o">=</span> <span class="n">Myset</span><span class="p">.</span><span class="n">insert</span><span class="p">(</span><span class="n">Value</span><span class="p">);</span>
<span class="n">assert</span><span class="p">(</span><span class="n">NewToSet</span> <span class="o">&&</span> <span class="s">"The value shouldn't be in the set yet"</span><span class="p">);</span>
</pre></div>
</div>
<p>These are two interesting different cases. In the first case, the call to
<code class="docutils literal notranslate"><span class="pre">V.size()</span></code> is only useful for the assert, and we don’t want it executed when
assertions are disabled. Code like this should move the call into the assert
itself. In the second case, the side effects of the call must happen whether
the assert is enabled or not. In this case, the value should be cast to void to
disable the warning. To be specific, it is preferred to write the code like
this:</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">assert</span><span class="p">(</span><span class="n">V</span><span class="p">.</span><span class="n">size</span><span class="p">()</span> <span class="o">></span> <span class="mi">42</span> <span class="o">&&</span> <span class="s">"Vector smaller than it should be"</span><span class="p">);</span>
<span class="kt">bool</span> <span class="n">NewToSet</span> <span class="o">=</span> <span class="n">Myset</span><span class="p">.</span><span class="n">insert</span><span class="p">(</span><span class="n">Value</span><span class="p">);</span> <span class="p">(</span><span class="kt">void</span><span class="p">)</span><span class="n">NewToSet</span><span class="p">;</span>
<span class="n">assert</span><span class="p">(</span><span class="n">NewToSet</span> <span class="o">&&</span> <span class="s">"The value shouldn't be in the set yet"</span><span class="p">);</span>
</pre></div>
</div>
</div>
<div class="section" id="do-not-use-using-namespace-std">
<h4><a class="toc-backref" href="#id45">Do Not Use <code class="docutils literal notranslate"><span class="pre">using</span> <span class="pre">namespace</span> <span class="pre">std</span></code></a><a class="headerlink" href="#do-not-use-using-namespace-std" title="Permalink to this headline">¶</a></h4>
<p>In LLVM, we prefer to explicitly prefix all identifiers from the standard
namespace with an “<code class="docutils literal notranslate"><span class="pre">std::</span></code>” prefix, rather than rely on “<code class="docutils literal notranslate"><span class="pre">using</span> <span class="pre">namespace</span>
<span class="pre">std;</span></code>”.</p>
<p>In header files, adding a <code class="docutils literal notranslate"><span class="pre">'using</span> <span class="pre">namespace</span> <span class="pre">XXX'</span></code> directive pollutes the
namespace of any source file that <code class="docutils literal notranslate"><span class="pre">#include</span></code>s the header, creating
maintenance issues.</p>
<p>In implementation files (e.g. <code class="docutils literal notranslate"><span class="pre">.cpp</span></code> files), the rule is more of a stylistic
rule, but is still important. Basically, using explicit namespace prefixes
makes the code <strong>clearer</strong>, because it is immediately obvious what facilities
are being used and where they are coming from. And <strong>more portable</strong>, because
namespace clashes cannot occur between LLVM code and other namespaces. The
portability rule is important because different standard library implementations
expose different symbols (potentially ones they shouldn’t), and future revisions
to the C++ standard will add more symbols to the <code class="docutils literal notranslate"><span class="pre">std</span></code> namespace. As such, we
never use <code class="docutils literal notranslate"><span class="pre">'using</span> <span class="pre">namespace</span> <span class="pre">std;'</span></code> in LLVM.</p>
<p>The exception to the general rule (i.e. it’s not an exception for the <code class="docutils literal notranslate"><span class="pre">std</span></code>
namespace) is for implementation files. For example, all of the code in the
LLVM project implements code that lives in the ‘llvm’ namespace. As such, it is
ok, and actually clearer, for the <code class="docutils literal notranslate"><span class="pre">.cpp</span></code> files to have a <code class="docutils literal notranslate"><span class="pre">'using</span> <span class="pre">namespace</span>
<span class="pre">llvm;'</span></code> directive at the top, after the <code class="docutils literal notranslate"><span class="pre">#include</span></code>s. This reduces
indentation in the body of the file for source editors that indent based on
braces, and keeps the conceptual context cleaner. The general form of this rule
is that any <code class="docutils literal notranslate"><span class="pre">.cpp</span></code> file that implements code in any namespace may use that
namespace (and its parents’), but should not use any others.</p>
</div>
<div class="section" id="provide-a-virtual-method-anchor-for-classes-in-headers">
<h4><a class="toc-backref" href="#id46">Provide a Virtual Method Anchor for Classes in Headers</a><a class="headerlink" href="#provide-a-virtual-method-anchor-for-classes-in-headers" title="Permalink to this headline">¶</a></h4>
<p>If a class is defined in a header file and has a vtable (either it has virtual
methods or it derives from classes with virtual methods), it must always have at
least one out-of-line virtual method in the class. Without this, the compiler
will copy the vtable and RTTI into every <code class="docutils literal notranslate"><span class="pre">.o</span></code> file that <code class="docutils literal notranslate"><span class="pre">#include</span></code>s the
header, bloating <code class="docutils literal notranslate"><span class="pre">.o</span></code> file sizes and increasing link times.</p>
</div>
<div class="section" id="don-t-use-default-labels-in-fully-covered-switches-over-enumerations">
<h4><a class="toc-backref" href="#id47">Don’t use default labels in fully covered switches over enumerations</a><a class="headerlink" href="#don-t-use-default-labels-in-fully-covered-switches-over-enumerations" title="Permalink to this headline">¶</a></h4>
<p><code class="docutils literal notranslate"><span class="pre">-Wswitch</span></code> warns if a switch, without a default label, over an enumeration
does not cover every enumeration value. If you write a default label on a fully
covered switch over an enumeration then the <code class="docutils literal notranslate"><span class="pre">-Wswitch</span></code> warning won’t fire
when new elements are added to that enumeration. To help avoid adding these
kinds of defaults, Clang has the warning <code class="docutils literal notranslate"><span class="pre">-Wcovered-switch-default</span></code> which is
off by default but turned on when building LLVM with a version of Clang that
supports the warning.</p>
<p>A knock-on effect of this stylistic requirement is that when building LLVM with
GCC you may get warnings related to “control may reach end of non-void function”
if you return from each case of a covered switch-over-enum because GCC assumes
that the enum expression may take any representable value, not just those of
individual enumerators. To suppress this warning, use <code class="docutils literal notranslate"><span class="pre">llvm_unreachable</span></code> after
the switch.</p>
</div>
<div class="section" id="use-range-based-for-loops-wherever-possible">
<h4><a class="toc-backref" href="#id48">Use range-based <code class="docutils literal notranslate"><span class="pre">for</span></code> loops wherever possible</a><a class="headerlink" href="#use-range-based-for-loops-wherever-possible" title="Permalink to this headline">¶</a></h4>
<p>The introduction of range-based <code class="docutils literal notranslate"><span class="pre">for</span></code> loops in C++11 means that explicit
manipulation of iterators is rarely necessary. We use range-based <code class="docutils literal notranslate"><span class="pre">for</span></code>
loops wherever possible for all newly added code. For example:</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">BasicBlock</span> <span class="o">*</span><span class="n">BB</span> <span class="o">=</span> <span class="p">...</span>
<span class="k">for</span> <span class="p">(</span><span class="n">Instruction</span> <span class="o">&</span><span class="nl">I</span> <span class="p">:</span> <span class="o">*</span><span class="n">BB</span><span class="p">)</span>
<span class="p">...</span> <span class="n">use</span> <span class="n">I</span> <span class="p">...</span>
</pre></div>
</div>
<p>Usage of <code class="docutils literal notranslate"><span class="pre">std::for_each()</span></code>/<code class="docutils literal notranslate"><span class="pre">llvm::for_each()</span></code> functions is discouraged,
unless the the callable object already exists.</p>
</div>
<div class="section" id="don-t-evaluate-end-every-time-through-a-loop">
<h4><a class="toc-backref" href="#id49">Don’t evaluate <code class="docutils literal notranslate"><span class="pre">end()</span></code> every time through a loop</a><a class="headerlink" href="#don-t-evaluate-end-every-time-through-a-loop" title="Permalink to this headline">¶</a></h4>
<p>In cases where range-based <code class="docutils literal notranslate"><span class="pre">for</span></code> loops can’t be used and it is necessary
to write an explicit iterator-based loop, pay close attention to whether
<code class="docutils literal notranslate"><span class="pre">end()</span></code> is re-evaluated on each loop iteration. One common mistake is to
write a loop in this style:</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">BasicBlock</span> <span class="o">*</span><span class="n">BB</span> <span class="o">=</span> <span class="p">...</span>
<span class="k">for</span> <span class="p">(</span><span class="k">auto</span> <span class="n">I</span> <span class="o">=</span> <span class="n">BB</span><span class="o">-></span><span class="n">begin</span><span class="p">();</span> <span class="n">I</span> <span class="o">!=</span> <span class="n">BB</span><span class="o">-></span><span class="n">end</span><span class="p">();</span> <span class="o">++</span><span class="n">I</span><span class="p">)</span>
<span class="p">...</span> <span class="n">use</span> <span class="n">I</span> <span class="p">...</span>
</pre></div>
</div>
<p>The problem with this construct is that it evaluates “<code class="docutils literal notranslate"><span class="pre">BB->end()</span></code>” every time
through the loop. Instead of writing the loop like this, we strongly prefer
loops to be written so that they evaluate it once before the loop starts. A
convenient way to do this is like so:</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">BasicBlock</span> <span class="o">*</span><span class="n">BB</span> <span class="o">=</span> <span class="p">...</span>
<span class="k">for</span> <span class="p">(</span><span class="k">auto</span> <span class="n">I</span> <span class="o">=</span> <span class="n">BB</span><span class="o">-></span><span class="n">begin</span><span class="p">(),</span> <span class="n">E</span> <span class="o">=</span> <span class="n">BB</span><span class="o">-></span><span class="n">end</span><span class="p">();</span> <span class="n">I</span> <span class="o">!=</span> <span class="n">E</span><span class="p">;</span> <span class="o">++</span><span class="n">I</span><span class="p">)</span>
<span class="p">...</span> <span class="n">use</span> <span class="n">I</span> <span class="p">...</span>
</pre></div>
</div>
<p>The observant may quickly point out that these two loops may have different
semantics: if the container (a basic block in this case) is being mutated, then
“<code class="docutils literal notranslate"><span class="pre">BB->end()</span></code>” may change its value every time through the loop and the second
loop may not in fact be correct. If you actually do depend on this behavior,
please write the loop in the first form and add a comment indicating that you
did it intentionally.</p>
<p>Why do we prefer the second form (when correct)? Writing the loop in the first
form has two problems. First it may be less efficient than evaluating it at the
start of the loop. In this case, the cost is probably minor — a few extra
loads every time through the loop. However, if the base expression is more
complex, then the cost can rise quickly. I’ve seen loops where the end
expression was actually something like: “<code class="docutils literal notranslate"><span class="pre">SomeMap[X]->end()</span></code>” and map lookups
really aren’t cheap. By writing it in the second form consistently, you
eliminate the issue entirely and don’t even have to think about it.</p>
<p>The second (even bigger) issue is that writing the loop in the first form hints
to the reader that the loop is mutating the container (a fact that a comment
would handily confirm!). If you write the loop in the second form, it is
immediately obvious without even looking at the body of the loop that the
container isn’t being modified, which makes it easier to read the code and
understand what it does.</p>
<p>While the second form of the loop is a few extra keystrokes, we do strongly
prefer it.</p>
</div>
<div class="section" id="include-iostream-is-forbidden">
<h4><a class="toc-backref" href="#id50"><code class="docutils literal notranslate"><span class="pre">#include</span> <span class="pre"><iostream></span></code> is Forbidden</a><a class="headerlink" href="#include-iostream-is-forbidden" title="Permalink to this headline">¶</a></h4>
<p>The use of <code class="docutils literal notranslate"><span class="pre">#include</span> <span class="pre"><iostream></span></code> in library files is hereby <strong>forbidden</strong>,
because many common implementations transparently inject a <a class="reference internal" href="#static-constructor">static constructor</a>
into every translation unit that includes it.</p>
<p>Note that using the other stream headers (<code class="docutils literal notranslate"><span class="pre"><sstream></span></code> for example) is not
problematic in this regard — just <code class="docutils literal notranslate"><span class="pre"><iostream></span></code>. However, <code class="docutils literal notranslate"><span class="pre">raw_ostream</span></code>
provides various APIs that are better performing for almost every use than
<code class="docutils literal notranslate"><span class="pre">std::ostream</span></code> style APIs.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>New code should always use <a class="reference internal" href="#raw-ostream">raw_ostream</a> for writing, or the
<code class="docutils literal notranslate"><span class="pre">llvm::MemoryBuffer</span></code> API for reading files.</p>
</div>
</div>
<div class="section" id="use-raw-ostream">
<span id="raw-ostream"></span><h4><a class="toc-backref" href="#id51">Use <code class="docutils literal notranslate"><span class="pre">raw_ostream</span></code></a><a class="headerlink" href="#use-raw-ostream" title="Permalink to this headline">¶</a></h4>
<p>LLVM includes a lightweight, simple, and efficient stream implementation in
<code class="docutils literal notranslate"><span class="pre">llvm/Support/raw_ostream.h</span></code>, which provides all of the common features of
<code class="docutils literal notranslate"><span class="pre">std::ostream</span></code>. All new code should use <code class="docutils literal notranslate"><span class="pre">raw_ostream</span></code> instead of
<code class="docutils literal notranslate"><span class="pre">ostream</span></code>.</p>
<p>Unlike <code class="docutils literal notranslate"><span class="pre">std::ostream</span></code>, <code class="docutils literal notranslate"><span class="pre">raw_ostream</span></code> is not a template and can be forward
declared as <code class="docutils literal notranslate"><span class="pre">class</span> <span class="pre">raw_ostream</span></code>. Public headers should generally not include
the <code class="docutils literal notranslate"><span class="pre">raw_ostream</span></code> header, but use forward declarations and constant references
to <code class="docutils literal notranslate"><span class="pre">raw_ostream</span></code> instances.</p>
</div>
<div class="section" id="avoid-std-endl">
<h4><a class="toc-backref" href="#id52">Avoid <code class="docutils literal notranslate"><span class="pre">std::endl</span></code></a><a class="headerlink" href="#avoid-std-endl" title="Permalink to this headline">¶</a></h4>
<p>The <code class="docutils literal notranslate"><span class="pre">std::endl</span></code> modifier, when used with <code class="docutils literal notranslate"><span class="pre">iostreams</span></code> outputs a newline to
the output stream specified. In addition to doing this, however, it also
flushes the output stream. In other words, these are equivalent:</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">std</span><span class="o">::</span><span class="n">cout</span> <span class="o"><<</span> <span class="n">std</span><span class="o">::</span><span class="n">endl</span><span class="p">;</span>
<span class="n">std</span><span class="o">::</span><span class="n">cout</span> <span class="o"><<</span> <span class="sc">'\n'</span> <span class="o"><<</span> <span class="n">std</span><span class="o">::</span><span class="n">flush</span><span class="p">;</span>
</pre></div>
</div>
<p>Most of the time, you probably have no reason to flush the output stream, so
it’s better to use a literal <code class="docutils literal notranslate"><span class="pre">'\n'</span></code>.</p>
</div>
<div class="section" id="don-t-use-inline-when-defining-a-function-in-a-class-definition">
<h4><a class="toc-backref" href="#id53">Don’t use <code class="docutils literal notranslate"><span class="pre">inline</span></code> when defining a function in a class definition</a><a class="headerlink" href="#don-t-use-inline-when-defining-a-function-in-a-class-definition" title="Permalink to this headline">¶</a></h4>
<p>A member function defined in a class definition is implicitly inline, so don’t
put the <code class="docutils literal notranslate"><span class="pre">inline</span></code> keyword in this case.</p>
<p>Don’t:</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">Foo</span> <span class="p">{</span>
<span class="k">public</span><span class="o">:</span>
<span class="kr">inline</span> <span class="kt">void</span> <span class="n">bar</span><span class="p">()</span> <span class="p">{</span>
<span class="c1">// ...</span>
<span class="p">}</span>
<span class="p">};</span>
</pre></div>
</div>
<p>Do:</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">Foo</span> <span class="p">{</span>
<span class="k">public</span><span class="o">:</span>
<span class="kt">void</span> <span class="n">bar</span><span class="p">()</span> <span class="p">{</span>
<span class="c1">// ...</span>
<span class="p">}</span>
<span class="p">};</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="microscopic-details">
<h3><a class="toc-backref" href="#id54">Microscopic Details</a><a class="headerlink" href="#microscopic-details" title="Permalink to this headline">¶</a></h3>
<p>This section describes preferred low-level formatting guidelines along with
reasoning on why we prefer them.</p>
<div class="section" id="spaces-before-parentheses">
<h4><a class="toc-backref" href="#id55">Spaces Before Parentheses</a><a class="headerlink" href="#spaces-before-parentheses" title="Permalink to this headline">¶</a></h4>
<p>Put a space before an open parenthesis only in control flow statements, but not
in normal function call expressions and function-like macros. For example:</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">if</span> <span class="p">(</span><span class="n">X</span><span class="p">)</span> <span class="p">...</span>
<span class="k">for</span> <span class="p">(</span><span class="n">I</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">I</span> <span class="o">!=</span> <span class="mi">100</span><span class="p">;</span> <span class="o">++</span><span class="n">I</span><span class="p">)</span> <span class="p">...</span>
<span class="k">while</span> <span class="p">(</span><span class="n">LLVMRocks</span><span class="p">)</span> <span class="p">...</span>
<span class="n">somefunc</span><span class="p">(</span><span class="mi">42</span><span class="p">);</span>
<span class="n">assert</span><span class="p">(</span><span class="mi">3</span> <span class="o">!=</span> <span class="mi">4</span> <span class="o">&&</span> <span class="s">"laws of math are failing me"</span><span class="p">);</span>
<span class="n">A</span> <span class="o">=</span> <span class="n">foo</span><span class="p">(</span><span class="mi">42</span><span class="p">,</span> <span class="mi">92</span><span class="p">)</span> <span class="o">+</span> <span class="n">bar</span><span class="p">(</span><span class="n">X</span><span class="p">);</span>
</pre></div>
</div>
<p>The reason for doing this is not completely arbitrary. This style makes control
flow operators stand out more, and makes expressions flow better.</p>
</div>
<div class="section" id="prefer-preincrement">
<h4><a class="toc-backref" href="#id56">Prefer Preincrement</a><a class="headerlink" href="#prefer-preincrement" title="Permalink to this headline">¶</a></h4>
<p>Hard fast rule: Preincrement (<code class="docutils literal notranslate"><span class="pre">++X</span></code>) may be no slower than postincrement
(<code class="docutils literal notranslate"><span class="pre">X++</span></code>) and could very well be a lot faster than it. Use preincrementation
whenever possible.</p>
<p>The semantics of postincrement include making a copy of the value being
incremented, returning it, and then preincrementing the “work value”. For
primitive types, this isn’t a big deal. But for iterators, it can be a huge
issue (for example, some iterators contains stack and set objects in them…
copying an iterator could invoke the copy ctor’s of these as well). In general,
get in the habit of always using preincrement, and you won’t have a problem.</p>
</div>
<div class="section" id="namespace-indentation">
<h4><a class="toc-backref" href="#id57">Namespace Indentation</a><a class="headerlink" href="#namespace-indentation" title="Permalink to this headline">¶</a></h4>
<p>In general, we strive to reduce indentation wherever possible. This is useful
because we want code to <a class="reference internal" href="#fit-into-80-columns">fit into 80 columns</a> without excessive wrapping, but
also because it makes it easier to understand the code. To facilitate this and
avoid some insanely deep nesting on occasion, don’t indent namespaces. If it
helps readability, feel free to add a comment indicating what namespace is
being closed by a <code class="docutils literal notranslate"><span class="pre">}</span></code>. For example:</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">namespace</span> <span class="n">llvm</span> <span class="p">{</span>
<span class="k">namespace</span> <span class="n">knowledge</span> <span class="p">{</span>
<span class="c1">/// This class represents things that Smith can have an intimate</span>
<span class="c1">/// understanding of and contains the data associated with it.</span>
<span class="k">class</span> <span class="nc">Grokable</span> <span class="p">{</span>
<span class="p">...</span>
<span class="k">public</span><span class="o">:</span>
<span class="k">explicit</span> <span class="n">Grokable</span><span class="p">()</span> <span class="p">{</span> <span class="p">...</span> <span class="p">}</span>
<span class="k">virtual</span> <span class="o">~</span><span class="n">Grokable</span><span class="p">()</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
<span class="p">...</span>
<span class="p">};</span>
<span class="p">}</span> <span class="c1">// end namespace knowledge</span>
<span class="p">}</span> <span class="c1">// end namespace llvm</span>
</pre></div>
</div>
<p>Feel free to skip the closing comment when the namespace being closed is
obvious for any reason. For example, the outer-most namespace in a header file
is rarely a source of confusion. But namespaces both anonymous and named in
source files that are being closed half way through the file probably could use
clarification.</p>
</div>
<div class="section" id="anonymous-namespaces">
<span id="static"></span><h4><a class="toc-backref" href="#id58">Anonymous Namespaces</a><a class="headerlink" href="#anonymous-namespaces" title="Permalink to this headline">¶</a></h4>
<p>After talking about namespaces in general, you may be wondering about anonymous
namespaces in particular. Anonymous namespaces are a great language feature
that tells the C++ compiler that the contents of the namespace are only visible
within the current translation unit, allowing more aggressive optimization and
eliminating the possibility of symbol name collisions. Anonymous namespaces are
to C++ as “static” is to C functions and global variables. While “<code class="docutils literal notranslate"><span class="pre">static</span></code>”
is available in C++, anonymous namespaces are more general: they can make entire
classes private to a file.</p>
<p>The problem with anonymous namespaces is that they naturally want to encourage
indentation of their body, and they reduce locality of reference: if you see a
random function definition in a C++ file, it is easy to see if it is marked
static, but seeing if it is in an anonymous namespace requires scanning a big
chunk of the file.</p>
<p>Because of this, we have a simple guideline: make anonymous namespaces as small
as possible, and only use them for class declarations. For example:</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">namespace</span> <span class="p">{</span>
<span class="k">class</span> <span class="nc">StringSort</span> <span class="p">{</span>
<span class="p">...</span>
<span class="k">public</span><span class="o">:</span>
<span class="n">StringSort</span><span class="p">(...)</span>
<span class="kt">bool</span> <span class="k">operator</span><span class="o"><</span><span class="p">(</span><span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">RHS</span><span class="p">)</span> <span class="k">const</span><span class="p">;</span>
<span class="p">};</span>
<span class="p">}</span> <span class="c1">// end anonymous namespace</span>
<span class="k">static</span> <span class="kt">void</span> <span class="n">runHelper</span><span class="p">()</span> <span class="p">{</span>
<span class="p">...</span>
<span class="p">}</span>
<span class="kt">bool</span> <span class="n">StringSort</span><span class="o">::</span><span class="k">operator</span><span class="o"><</span><span class="p">(</span><span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">RHS</span><span class="p">)</span> <span class="k">const</span> <span class="p">{</span>
<span class="p">...</span>
<span class="p">}</span>
</pre></div>
</div>
<p>Avoid putting declarations other than classes into anonymous namespaces:</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">namespace</span> <span class="p">{</span>
<span class="c1">// ... many declarations ...</span>
<span class="kt">void</span> <span class="nf">runHelper</span><span class="p">()</span> <span class="p">{</span>
<span class="p">...</span>
<span class="p">}</span>
<span class="c1">// ... many declarations ...</span>
<span class="p">}</span> <span class="c1">// end anonymous namespace</span>
</pre></div>
</div>
<p>When you are looking at “<code class="docutils literal notranslate"><span class="pre">runHelper</span></code>” in the middle of a large C++ file,
you have no immediate way to tell if this function is local to the file. In
contrast, when the function is marked static, you don’t need to cross-reference
faraway places in the file to tell that the function is local.</p>
</div>
<div class="section" id="don-t-use-braces-on-simple-single-statement-bodies-of-if-else-loop-statements">
<h4><a class="toc-backref" href="#id59">Don’t Use Braces on Simple Single-Statement Bodies of if/else/loop Statements</a><a class="headerlink" href="#don-t-use-braces-on-simple-single-statement-bodies-of-if-else-loop-statements" title="Permalink to this headline">¶</a></h4>
<p>When writing the body of an <code class="docutils literal notranslate"><span class="pre">if</span></code>, <code class="docutils literal notranslate"><span class="pre">else</span></code>, or loop statement, we prefer to
omit the braces to avoid unnecessary line noise. However, braces should be used
in cases where the omission of braces harm the readability and maintainability
of the code.</p>
<p>We consider that readability is harmed when omitting the brace in the presence
of a single statement that is accompanied by a comment (assuming the comment
can’t be hoisted above the <code class="docutils literal notranslate"><span class="pre">if</span></code> or loop statement, see below).
Similarly, braces should be used when a single-statement body is complex enough
that it becomes difficult to see where the block containing the following
statement began. An <code class="docutils literal notranslate"><span class="pre">if</span></code>/<code class="docutils literal notranslate"><span class="pre">else</span></code> chain or a loop is considered a single
statement for this rule, and this rule applies recursively.</p>
<p>This list is not exhaustive, for example, readability is also harmed if an
<code class="docutils literal notranslate"><span class="pre">if</span></code>/<code class="docutils literal notranslate"><span class="pre">else</span></code> chain does not use braced bodies for either all or none of its
members, with complex conditionals, deep nesting, etc. The examples below
intend to provide some guidelines.</p>
<p>Maintainability is harmed if the body of an <code class="docutils literal notranslate"><span class="pre">if</span></code> ends with a (directly or
indirectly) nested <code class="docutils literal notranslate"><span class="pre">if</span></code> statement with no <code class="docutils literal notranslate"><span class="pre">else</span></code>. Braces on the outer <code class="docutils literal notranslate"><span class="pre">if</span></code>
would help to avoid running into a “dangling else” situation.</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="c1">// Omit the braces, since the body is simple and clearly associated with the if.</span>
<span class="k">if</span> <span class="p">(</span><span class="n">isa</span><span class="o"><</span><span class="n">FunctionDecl</span><span class="o">></span><span class="p">(</span><span class="n">D</span><span class="p">))</span>
<span class="n">handleFunctionDecl</span><span class="p">(</span><span class="n">D</span><span class="p">);</span>
<span class="k">else</span> <span class="nf">if</span> <span class="p">(</span><span class="n">isa</span><span class="o"><</span><span class="n">VarDecl</span><span class="o">></span><span class="p">(</span><span class="n">D</span><span class="p">))</span>
<span class="n">handleVarDecl</span><span class="p">(</span><span class="n">D</span><span class="p">);</span>
<span class="c1">// Here we document the condition itself and not the body.</span>
<span class="k">if</span> <span class="p">(</span><span class="n">isa</span><span class="o"><</span><span class="n">VarDecl</span><span class="o">></span><span class="p">(</span><span class="n">D</span><span class="p">))</span> <span class="p">{</span>
<span class="c1">// It is necessary that we explain the situation with this surprisingly long</span>
<span class="c1">// comment, so it would be unclear without the braces whether the following</span>
<span class="c1">// statement is in the scope of the `if`.</span>
<span class="c1">// Because the condition is documented, we can't really hoist this</span>
<span class="c1">// comment that applies to the body above the if.</span>
<span class="n">handleOtherDecl</span><span class="p">(</span><span class="n">D</span><span class="p">);</span>
<span class="p">}</span>
<span class="c1">// Use braces on the outer `if` to avoid a potential dangling else situation.</span>
<span class="k">if</span> <span class="p">(</span><span class="n">isa</span><span class="o"><</span><span class="n">VarDecl</span><span class="o">></span><span class="p">(</span><span class="n">D</span><span class="p">))</span> <span class="p">{</span>
<span class="k">for</span> <span class="p">(</span><span class="k">auto</span> <span class="o">*</span><span class="nl">A</span> <span class="p">:</span> <span class="n">D</span><span class="p">.</span><span class="n">attrs</span><span class="p">())</span>
<span class="k">if</span> <span class="p">(</span><span class="n">shouldProcessAttr</span><span class="p">(</span><span class="n">A</span><span class="p">))</span>
<span class="n">handleAttr</span><span class="p">(</span><span class="n">A</span><span class="p">);</span>
<span class="p">}</span>
<span class="c1">// Use braces for the `if` block to keep it uniform with the else block.</span>
<span class="k">if</span> <span class="p">(</span><span class="n">isa</span><span class="o"><</span><span class="n">FunctionDecl</span><span class="o">></span><span class="p">(</span><span class="n">D</span><span class="p">))</span> <span class="p">{</span>
<span class="n">handleFunctionDecl</span><span class="p">(</span><span class="n">D</span><span class="p">);</span>
<span class="p">}</span> <span class="k">else</span> <span class="p">{</span>
<span class="c1">// In this else case, it is necessary that we explain the situation with this</span>
<span class="c1">// surprisingly long comment, so it would be unclear without the braces whether</span>
<span class="c1">// the following statement is in the scope of the `if`.</span>
<span class="n">handleOtherDecl</span><span class="p">(</span><span class="n">D</span><span class="p">);</span>
<span class="p">}</span>
<span class="c1">// This should also omit braces. The `for` loop contains only a single statement,</span>
<span class="c1">// so it shouldn't have braces. The `if` also only contains a single simple</span>
<span class="c1">// statement (the for loop), so it also should omit braces.</span>
<span class="k">if</span> <span class="p">(</span><span class="n">isa</span><span class="o"><</span><span class="n">FunctionDecl</span><span class="o">></span><span class="p">(</span><span class="n">D</span><span class="p">))</span>
<span class="k">for</span> <span class="p">(</span><span class="k">auto</span> <span class="o">*</span><span class="nl">A</span> <span class="p">:</span> <span class="n">D</span><span class="p">.</span><span class="n">attrs</span><span class="p">())</span>
<span class="n">handleAttr</span><span class="p">(</span><span class="n">A</span><span class="p">);</span>
<span class="c1">// Use braces for the outer `if` since the nested `for` is braced.</span>
<span class="k">if</span> <span class="p">(</span><span class="n">isa</span><span class="o"><</span><span class="n">FunctionDecl</span><span class="o">></span><span class="p">(</span><span class="n">D</span><span class="p">))</span> <span class="p">{</span>
<span class="k">for</span> <span class="p">(</span><span class="k">auto</span> <span class="o">*</span><span class="nl">A</span> <span class="p">:</span> <span class="n">D</span><span class="p">.</span><span class="n">attrs</span><span class="p">())</span> <span class="p">{</span>
<span class="c1">// In this for loop body, it is necessary that we explain the situation</span>
<span class="c1">// with this surprisingly long comment, forcing braces on the `for` block.</span>
<span class="n">handleAttr</span><span class="p">(</span><span class="n">A</span><span class="p">);</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="c1">// Use braces on the outer block because there are more than two levels of nesting.</span>
<span class="k">if</span> <span class="p">(</span><span class="n">isa</span><span class="o"><</span><span class="n">FunctionDecl</span><span class="o">></span><span class="p">(</span><span class="n">D</span><span class="p">))</span> <span class="p">{</span>
<span class="k">for</span> <span class="p">(</span><span class="k">auto</span> <span class="o">*</span><span class="nl">A</span> <span class="p">:</span> <span class="n">D</span><span class="p">.</span><span class="n">attrs</span><span class="p">())</span>
<span class="k">for</span> <span class="p">(</span><span class="kt">ssize_t</span> <span class="nl">i</span> <span class="p">:</span> <span class="n">llvm</span><span class="o">::</span><span class="n">seq</span><span class="o"><</span><span class="kt">ssize_t</span><span class="o">></span><span class="p">(</span><span class="n">count</span><span class="p">))</span>
<span class="n">handleAttrOnDecl</span><span class="p">(</span><span class="n">D</span><span class="p">,</span> <span class="n">A</span><span class="p">,</span> <span class="n">i</span><span class="p">);</span>
<span class="p">}</span>
<span class="c1">// Use braces on the outer block because of a nested `if`, otherwise the</span>
<span class="c1">// compiler would warn: `add explicit braces to avoid dangling else`</span>
<span class="k">if</span> <span class="p">(</span><span class="k">auto</span> <span class="o">*</span><span class="n">D</span> <span class="o">=</span> <span class="n">dyn_cast</span><span class="o"><</span><span class="n">FunctionDecl</span><span class="o">></span><span class="p">(</span><span class="n">D</span><span class="p">))</span> <span class="p">{</span>
<span class="k">if</span> <span class="p">(</span><span class="n">shouldProcess</span><span class="p">(</span><span class="n">D</span><span class="p">))</span>
<span class="n">handleVarDecl</span><span class="p">(</span><span class="n">D</span><span class="p">);</span>
<span class="k">else</span>
<span class="nf">markAsIgnored</span><span class="p">(</span><span class="n">D</span><span class="p">);</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
</div>
</div>
<div class="section" id="see-also">
<h2><a class="toc-backref" href="#id60">See Also</a><a class="headerlink" href="#see-also" title="Permalink to this headline">¶</a></h2>
<p>A lot of these comments and recommendations have been culled from other sources.
Two particularly important books for our work are:</p>
<ol class="arabic simple">
<li><p><a class="reference external" href="https://www.amazon.com/Effective-Specific-Addison-Wesley-Professional-Computing/dp/0321334876">Effective C++</a>
by Scott Meyers. Also interesting and useful are “More Effective C++” and
“Effective STL” by the same author.</p></li>
<li><p><a class="reference external" href="https://www.amazon.com/Large-Scale-Software-Design-John-Lakos/dp/0201633620">Large-Scale C++ Software Design</a>
by John Lakos</p></li>
</ol>
<p>If you get some free time, and you haven’t read them: do so, you might learn
something.</p>
</div>
</div>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="GitBisecting.html" title="Bisecting LLVM code"
>next</a> |</li>
<li class="right" >
<a href="BugLifeCycle.html" title="LLVM Bug Life Cycle"
>previous</a> |</li>
<li><a href="https://llvm.org/">LLVM Home</a> | </li>
<li><a href="index.html">Documentation</a>»</li>
<li class="nav-item nav-item-1"><a href="GettingInvolved.html" >Getting Involved</a> »</li>
<li class="nav-item nav-item-this"><a href="">LLVM Coding Standards</a></li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright 2003-2021, LLVM Project.
Last updated on 2021-09-18.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 3.5.4.
</div>
</body>
</html>
|
