Skip to content

Commit 966dc7a

Browse files
claremacraeclaremacrae
committed
Add table of contents to pages with more than one section
Done with the command: `doctoc --title **Contents** . --maxlevel 2` (after placing empty doctoc markers just after each .md file'd level-1 heading.) This is demonstrate the benafits of cpp-best-practices#103
1 parent 31cef74 commit 966dc7a

13 files changed

+127
-0
lines changed

‎01-Preface.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,8 @@
11
# Preface
22

3+
<!-- START doctoc -->
4+
<!-- END doctoc -->
5+
36
C++ Best Practices: A Forkable Coding Standards Document
47

58
This document is meant to be a collaborative discussion of the best practices in C++. It complements books such as *Effective C++* (Meyers) and *C++ Coding Standards* (Alexandrescu, Sutter). We fill in some of the lower level details that they don't discuss and provide specific stylistic recommendations while also discussing how to ensure overall code quality.

‎02-Use_the_Tools_Available.md

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,24 @@
11
# Use The Tools Available
22

3+
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
4+
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
5+
**Contents**
6+
7+
- [Source Control](#source-control)
8+
- [Build Tool](#build-tool)
9+
- [Package Manager](#package-manager)
10+
- [Continuous Integration](#continuous-integration)
11+
- [Compilers](#compilers)
12+
- [LLVM-based tools](#llvm-based-tools)
13+
- [Static Analyzers](#static-analyzers)
14+
- [Runtime Checkers](#runtime-checkers)
15+
- [Ignoring Warnings](#ignoring-warnings)
16+
- [Testing](#testing)
17+
- [Debugging](#debugging)
18+
- [Other Tools](#other-tools)
19+
20+
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
21+
322
An automated framework for executing these tools should be established very early in the development process. It should not take more than 2-3 commands to checkout the source code, build, and execute the tests. Once the tests are done executing, you should have an almost complete picture of the state and quality of the code.
423

524
## Source Control

‎03-Style.md

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,36 @@
11
# Style
22

3+
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
4+
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
5+
**Contents**
6+
7+
- [Establishing A Style Guideline](#establishing-a-style-guideline)
8+
- [Common C++ Naming Conventions](#common-c-naming-conventions)
9+
- [Distinguish Private Object Data](#distinguish-private-object-data)
10+
- [Distinguish Function Parameters](#distinguish-function-parameters)
11+
- [Don't Name Anything Starting With `_`](#dont-name-anything-starting-with-_)
12+
- [Well-Formed Example](#well-formed-example)
13+
- [Enable Out-of-Source-Directory Builds](#enable-out-of-source-directory-builds)
14+
- [Use `nullptr`](#use-nullptr)
15+
- [Comments](#comments)
16+
- [Never Use `using namespace` in a Header File](#never-use-using-namespace-in-a-header-file)
17+
- [Include Guards](#include-guards)
18+
- [{} Are Required for Blocks.](#-are-required-for-blocks)
19+
- [Keep Lines a Reasonable Length](#keep-lines-a-reasonable-length)
20+
- [Use "" for Including Local Files](#use--for-including-local-files)
21+
- [Initialize Member Variables](#initialize-member-variables)
22+
- [Always Use Namespaces](#always-use-namespaces)
23+
- [Use the Correct Integer Type for Standard Library Features](#use-the-correct-integer-type-for-standard-library-features)
24+
- [Use .hpp and .cpp for Your File Extensions](#use-hpp-and-cpp-for-your-file-extensions)
25+
- [Never Mix Tabs and Spaces](#never-mix-tabs-and-spaces)
26+
- [Never Put Code with Side Effects Inside an assert()](#never-put-code-with-side-effects-inside-an-assert)
27+
- [Don't Be Afraid of Templates](#dont-be-afraid-of-templates)
28+
- [Use Operator Overloads Judiciously](#use-operator-overloads-judiciously)
29+
- [Avoid Implicit Conversions](#avoid-implicit-conversions)
30+
- [Consider the Rule of Zero](#consider-the-rule-of-zero)
31+
32+
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
33+
334
Consistency is the most important aspect of style. The second most important aspect is following a style that the average C++ programmer is used to reading.
435

536
C++ allows for arbitrary-length identifier names, so there's no reason to be terse when naming things. Use descriptive names, and be consistent in the style.

‎04-Considering_Safety.md

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,18 @@
11
# Considering Safety
22

3+
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
4+
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
5+
**Contents**
6+
7+
- [Const as Much as Possible](#const-as-much-as-possible)
8+
- [Avoid Raw Memory Access](#avoid-raw-memory-access)
9+
- [Use `std::array` or `std::vector` Instead of C-style Arrays](#use-stdarray-or-stdvector-instead-of-c-style-arrays)
10+
- [Use Exceptions](#use-exceptions)
11+
- [Use C++-style cast instead of C-style cast](#use-c-style-cast-instead-of-c-style-cast)
12+
- [Do not define a variadic function](#do-not-define-a-variadic-function)
13+
- [Additional Resources](#additional-resources)
14+
15+
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
316

417
## Const as Much as Possible
518
`const` tells the compiler that a variable or method is immutable. This helps the compiler optimize the code and helps the developer know if a function has a side effect. Also, using `const &` prevents the compiler from copying data unnecessarily. The [comments on `const` from John Carmack](http://kotaku.com/454293019) are also a good read.

‎05-Considering_Maintainability.md

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,16 @@
11
# Considering Maintainability
22

3+
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
4+
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
5+
**Contents**
6+
7+
- [Avoid Compiler Macros](#avoid-compiler-macros)
8+
- [Consider Avoiding Boolean Parameters](#consider-avoiding-boolean-parameters)
9+
- [Avoid Raw Loops](#avoid-raw-loops)
10+
- [Never Use `assert` With Side Effects](#never-use-assert-with-side-effects)
11+
- [Properly Utilize 'override' and 'final'](#properly-utilize-override-and-final)
12+
13+
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
314

415
## Avoid Compiler Macros
516

‎06-Considering_Portability.md

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,15 @@
11
# Considering Portability
22

3+
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
4+
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
5+
**Contents**
6+
7+
- [Know Your Types](#know-your-types)
8+
- [Use The Standard Library](#use-the-standard-library)
9+
- [Other Concerns](#other-concerns)
10+
11+
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
12+
313
## Know Your Types
414

515
Most portability issues that generate warnings are because we are not careful about our types. Standard library and arrays are indexed with `size_t`. Standard container sizes are reported in `size_t`. If you get the handling of `size_t` wrong, you can create subtle lurking 64-bit issues that arise only after you start to overflow the indexing of 32-bit integers. char vs unsigned char.

‎07-Considering_Threadability.md

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,15 @@
11
# Considering Threadability
22

3+
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
4+
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
5+
**Contents**
6+
7+
- [Avoid Global Data](#avoid-global-data)
8+
- [Avoid Heap Operations](#avoid-heap-operations)
9+
- [Mutex and mutable go together (M&M rule, C++11)](#mutex-and-mutable-go-together-mm-rule-c11)
10+
11+
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
12+
313
## Avoid Global Data
414

515
Global data leads to unintended side effects between functions and can make code difficult or impossible to parallelize. Even if the code is not intended today for parallelization, there is no reason to make it impossible for the future.

‎08-Considering_Performance.md

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,14 @@
11
# Considering Performance
22

3+
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
4+
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
5+
**Contents**
6+
7+
- [Build Time](#build-time)
8+
- [Runtime](#runtime)
9+
10+
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
11+
312
## Build Time
413

514

‎09-Enable_Scripting.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,8 @@
11
# Enable Scripting
22

3+
<!-- START doctoc -->
4+
<!-- END doctoc -->
5+
36
The combination of scripting and compiled languages is very powerful. It gives us the things we've come to love about compiled languages: type safety, performance, thread safety options, consistent memory model while also giving us the flexibility to try something new quickly without a full rebuild.
47

58
The VM based compiled languages have learned this already: JRuby, Jython, IronRuby, IronPython

‎10-Further_Reading.md

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,14 @@
11
# Further Reading
22

3+
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
4+
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
5+
**Contents**
6+
7+
- [C++](#c)
8+
- [CMake](#cmake)
9+
10+
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
11+
312
*Note: This book has now inspired a video series from O'Reilly, [Learning C++ Best Practices](http://shop.oreilly.com/product/0636920049814.do)*
413

514
## C++

‎11-Final_Thoughts.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,7 @@
11
# Final Thoughts
22

3+
<!-- START doctoc -->
4+
<!-- END doctoc -->
5+
36
Expand your horizons and use other programming languages. Other languages have different constructs and expressions. Learning what else is out there will encourage you to be more creative with your C++ and write cleaner, more expressive code.
47

‎README.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,8 @@
11
# cppbestpractices
22

3+
<!-- START doctoc -->
4+
<!-- END doctoc -->
5+
36
[![Join the chat at https://gitter.im/lefticus/cppbestpractices](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/lefticus/cppbestpractices?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
47

58
Collaborative Collection of C++ Best Practices

‎SUMMARY.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,8 @@
11
# Summary
22

3+
<!-- START doctoc -->
4+
<!-- END doctoc -->
5+
36
* [Preface](01-Preface.md)
47
* [Use the Tools Available](02-Use_the_Tools_Available.md)
58
* [Style](03-Style.md)

0 commit comments

Comments
 (0)