Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
154 changes: 77 additions & 77 deletions docs/spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ It carries
## Purpose

<!-- tl:item INT-0001 -->
**INT-0001 — C++ is written in one consistent, safe, maintainable style** — `intent`, status `approved`
**INT-0001 — C++ is written in one consistent, safe, maintainable style** — `intent`, status `proposed`

> The Google C++ Style Guide exists so that C++ across a large codebase reads as though written by one author: consistent header structure, scoping, class design, naming, commenting and formatting, biased towards the safe and predictable subset of a large and dangerous language, so that any engineer can read and change code they did not write and avoid the language's many footguns.

Expand All @@ -25,7 +25,7 @@ It carries
## Header Files

<!-- tl:item UR-0001 -->
**UR-0001 — Header Files** — `user_requirement`, status `approved`
**UR-0001 — Header Files** — `user_requirement`, status `proposed`

> Rules governing self-contained headers, include guards, what to include, forward declarations, inline definitions and the order of includes.

Expand All @@ -37,18 +37,18 @@ It carries
<!-- tl:table type == 'system_requirement' and attrs.get('source_ref', '').startswith('Google C++ Style Guide: Header Files') -->
| UID | Type | Status | Title |
|---|---|---|---|
| SR-0001 | system_requirement | approved | Make every header self-contained |
| SR-0002 | system_requirement | approved | Guard every header against multiple inclusion |
| SR-0003 | system_requirement | approved | Include every header you directly use |
| SR-0004 | system_requirement | approved | Avoid forward declarations; include the header |
| SR-0005 | system_requirement | approved | Only define short functions inline in a header |
| SR-0006 | system_requirement | approved | Order and group includes consistently |
| SR-0001 | system_requirement | proposed | Make every header self-contained |
| SR-0002 | system_requirement | proposed | Guard every header against multiple inclusion |
| SR-0003 | system_requirement | proposed | Include every header you directly use |
| SR-0004 | system_requirement | proposed | Avoid forward declarations; include the header |
| SR-0005 | system_requirement | proposed | Only define short functions inline in a header |
| SR-0006 | system_requirement | proposed | Order and group includes consistently |
<!-- tl:end -->

## Scoping

<!-- tl:item UR-0002 -->
**UR-0002 — Scoping** — `user_requirement`, status `approved`
**UR-0002 — Scoping** — `user_requirement`, status `proposed`

> Rules governing namespaces, internal linkage, nonmember functions, local variables and static, global and thread-local storage.

Expand All @@ -60,18 +60,18 @@ It carries
<!-- tl:table type == 'system_requirement' and attrs.get('source_ref', '').startswith('Google C++ Style Guide: Scoping') -->
| UID | Type | Status | Title |
|---|---|---|---|
| SR-0007 | system_requirement | approved | Place code in a uniquely named namespace |
| SR-0008 | system_requirement | approved | Give .cc-only code internal linkage |
| SR-0009 | system_requirement | approved | Prefer nonmember functions in a namespace to static members |
| SR-0010 | system_requirement | approved | Declare each local variable in the narrowest scope |
| SR-0011 | system_requirement | approved | Forbid non-trivially-destructible static and global objects |
| SR-0012 | system_requirement | approved | Constant-initialise every thread_local at namespace or class scope |
| SR-0007 | system_requirement | proposed | Place code in a uniquely named namespace |
| SR-0008 | system_requirement | proposed | Give .cc-only code internal linkage |
| SR-0009 | system_requirement | proposed | Prefer nonmember functions in a namespace to static members |
| SR-0010 | system_requirement | proposed | Declare each local variable in the narrowest scope |
| SR-0011 | system_requirement | proposed | Forbid non-trivially-destructible static and global objects |
| SR-0012 | system_requirement | proposed | Constant-initialise every thread_local at namespace or class scope |
<!-- tl:end -->

## Classes

<!-- tl:item UR-0003 -->
**UR-0003 — Classes** — `user_requirement`, status `approved`
**UR-0003 — Classes** — `user_requirement`, status `proposed`

> Rules governing constructors, implicit conversions, copy and move semantics, structs versus classes, inheritance, operator overloading, access control and declaration order.

Expand All @@ -83,21 +83,21 @@ It carries
<!-- tl:table type == 'system_requirement' and attrs.get('source_ref', '').startswith('Google C++ Style Guide: Classes') -->
| UID | Type | Status | Title |
|---|---|---|---|
| SR-0013 | system_requirement | approved | Do minimal, error-free work in constructors |
| SR-0014 | system_requirement | approved | Mark single-argument constructors and conversion operators explicit |
| SR-0015 | system_requirement | approved | Declare or delete copy and move operations deliberately |
| SR-0016 | system_requirement | approved | Use struct only for passive data carriers |
| SR-0017 | system_requirement | approved | Prefer a named struct to a pair or tuple |
| SR-0018 | system_requirement | approved | Make inheritance public and prefer composition |
| SR-0019 | system_requirement | approved | Overload operators only with obvious meaning |
| SR-0020 | system_requirement | approved | Keep all data members private |
| SR-0021 | system_requirement | approved | Order class declarations by kind and visibility |
| SR-0013 | system_requirement | proposed | Do minimal, error-free work in constructors |
| SR-0014 | system_requirement | proposed | Mark single-argument constructors and conversion operators explicit |
| SR-0015 | system_requirement | proposed | Declare or delete copy and move operations deliberately |
| SR-0016 | system_requirement | proposed | Use struct only for passive data carriers |
| SR-0017 | system_requirement | proposed | Prefer a named struct to a pair or tuple |
| SR-0018 | system_requirement | proposed | Make inheritance public and prefer composition |
| SR-0019 | system_requirement | proposed | Overload operators only with obvious meaning |
| SR-0020 | system_requirement | proposed | Keep all data members private |
| SR-0021 | system_requirement | proposed | Order class declarations by kind and visibility |
<!-- tl:end -->

## Functions

<!-- tl:item UR-0004 -->
**UR-0004 — Functions** — `user_requirement`, status `approved`
**UR-0004 — Functions** — `user_requirement`, status `proposed`

> Rules governing inputs and outputs, function length, overloading, default arguments and trailing return types.

Expand All @@ -109,17 +109,17 @@ It carries
<!-- tl:table type == 'system_requirement' and attrs.get('source_ref', '').startswith('Google C++ Style Guide: Functions') -->
| UID | Type | Status | Title |
|---|---|---|---|
| SR-0022 | system_requirement | approved | Prefer return values to output parameters |
| SR-0023 | system_requirement | approved | Write short, focused functions |
| SR-0024 | system_requirement | approved | Overload only when the call is unambiguous to a reader |
| SR-0025 | system_requirement | approved | Restrict default arguments to non-virtual functions |
| SR-0026 | system_requirement | approved | Use a trailing return type only when it helps |
| SR-0022 | system_requirement | proposed | Prefer return values to output parameters |
| SR-0023 | system_requirement | proposed | Write short, focused functions |
| SR-0024 | system_requirement | proposed | Overload only when the call is unambiguous to a reader |
| SR-0025 | system_requirement | proposed | Restrict default arguments to non-virtual functions |
| SR-0026 | system_requirement | proposed | Use a trailing return type only when it helps |
<!-- tl:end -->

## Ownership and Smart Pointers

<!-- tl:item UR-0005 -->
**UR-0005 — Ownership and Smart Pointers** — `user_requirement`, status `approved`
**UR-0005 — Ownership and Smart Pointers** — `user_requirement`, status `proposed`

> Rules governing dynamic allocation, single ownership and the use of smart pointers.

Expand All @@ -131,15 +131,15 @@ It carries
<!-- tl:table type == 'system_requirement' and attrs.get('source_ref', '').startswith('Google C++ Style Guide: Ownership') -->
| UID | Type | Status | Title |
|---|---|---|---|
| SR-0027 | system_requirement | approved | Give every dynamic object a single fixed owner |
| SR-0028 | system_requirement | approved | Transfer ownership with std::unique_ptr |
| SR-0029 | system_requirement | approved | Use std::shared_ptr only when sharing is truly needed |
| SR-0027 | system_requirement | proposed | Give every dynamic object a single fixed owner |
| SR-0028 | system_requirement | proposed | Transfer ownership with std::unique_ptr |
| SR-0029 | system_requirement | proposed | Use std::shared_ptr only when sharing is truly needed |
<!-- tl:end -->

## Other C++ Features

<!-- tl:item UR-0006 -->
**UR-0006 — Other C++ Features** — `user_requirement`, status `approved`
**UR-0006 — Other C++ Features** — `user_requirement`, status `proposed`

> Rules governing rvalue references, exceptions, RTTI, casting, streams, const, constexpr, integer types, macros, nullptr, auto and lambdas.

Expand All @@ -151,25 +151,25 @@ It carries
<!-- tl:table type == 'system_requirement' and attrs.get('source_ref', '').startswith('Google C++ Style Guide: Other C++ Features') -->
| UID | Type | Status | Title |
|---|---|---|---|
| SR-0030 | system_requirement | approved | Restrict rvalue references to move and forwarding code |
| SR-0031 | system_requirement | approved | Do not use C++ exceptions |
| SR-0032 | system_requirement | approved | Specify noexcept only when it is accurate and useful |
| SR-0033 | system_requirement | approved | Avoid RTTI in production code |
| SR-0034 | system_requirement | approved | Use C++-style casts, never C-style casts |
| SR-0035 | system_requirement | approved | Use streams only for local human-readable output |
| SR-0036 | system_requirement | approved | Use const wherever it is meaningful |
| SR-0037 | system_requirement | approved | Use constexpr and constinit for compile-time values |
| SR-0038 | system_requirement | approved | Use sized integer types from <cstdint> |
| SR-0039 | system_requirement | approved | Avoid the preprocessor; prefer inline, const and constexpr |
| SR-0040 | system_requirement | approved | Use nullptr for pointers and '\0' for characters |
| SR-0041 | system_requirement | approved | Use auto only where it aids readability |
| SR-0042 | system_requirement | approved | Use lambda expressions judiciously with explicit captures |
| SR-0030 | system_requirement | proposed | Restrict rvalue references to move and forwarding code |
| SR-0031 | system_requirement | proposed | Do not use C++ exceptions |
| SR-0032 | system_requirement | proposed | Specify noexcept only when it is accurate and useful |
| SR-0033 | system_requirement | proposed | Avoid RTTI in production code |
| SR-0034 | system_requirement | proposed | Use C++-style casts, never C-style casts |
| SR-0035 | system_requirement | proposed | Use streams only for local human-readable output |
| SR-0036 | system_requirement | proposed | Use const wherever it is meaningful |
| SR-0037 | system_requirement | proposed | Use constexpr and constinit for compile-time values |
| SR-0038 | system_requirement | proposed | Use sized integer types from <cstdint> |
| SR-0039 | system_requirement | proposed | Avoid the preprocessor; prefer inline, const and constexpr |
| SR-0040 | system_requirement | proposed | Use nullptr for pointers and '\0' for characters |
| SR-0041 | system_requirement | proposed | Use auto only where it aids readability |
| SR-0042 | system_requirement | proposed | Use lambda expressions judiciously with explicit captures |
<!-- tl:end -->

## Naming

<!-- tl:item UR-0007 -->
**UR-0007 — Naming** — `user_requirement`, status `approved`
**UR-0007 — Naming** — `user_requirement`, status `proposed`

> Rules governing the casing and choice of file, type, variable, constant, function, namespace, enumerator and macro names.

Expand All @@ -181,20 +181,20 @@ It carries
<!-- tl:table type == 'system_requirement' and attrs.get('source_ref', '').startswith('Google C++ Style Guide: Naming') -->
| UID | Type | Status | Title |
|---|---|---|---|
| SR-0043 | system_requirement | approved | Choose descriptive names over abbreviations |
| SR-0044 | system_requirement | approved | Name files in lowercase with underscores |
| SR-0045 | system_requirement | approved | Name types in UpperCamelCase |
| SR-0046 | system_requirement | approved | Name variables in snake_case with a trailing underscore on members |
| SR-0047 | system_requirement | approved | Name constants and enumerators with a leading k |
| SR-0048 | system_requirement | approved | Name functions in UpperCamelCase |
| SR-0049 | system_requirement | approved | Name namespaces in snake_case, avoiding generic names |
| SR-0050 | system_requirement | approved | Name macros in ALL_CAPS with a project prefix |
| SR-0043 | system_requirement | proposed | Choose descriptive names over abbreviations |
| SR-0044 | system_requirement | proposed | Name files in lowercase with underscores |
| SR-0045 | system_requirement | proposed | Name types in UpperCamelCase |
| SR-0046 | system_requirement | proposed | Name variables in snake_case with a trailing underscore on members |
| SR-0047 | system_requirement | proposed | Name constants and enumerators with a leading k |
| SR-0048 | system_requirement | proposed | Name functions in UpperCamelCase |
| SR-0049 | system_requirement | proposed | Name namespaces in snake_case, avoiding generic names |
| SR-0050 | system_requirement | proposed | Name macros in ALL_CAPS with a project prefix |
<!-- tl:end -->

## Comments

<!-- tl:item UR-0008 -->
**UR-0008 — Comments** — `user_requirement`, status `approved`
**UR-0008 — Comments** — `user_requirement`, status `proposed`

> Rules governing comment style, file, class, function and variable comments, implementation comments and TODOs.

Expand All @@ -206,19 +206,19 @@ It carries
<!-- tl:table type == 'system_requirement' and attrs.get('source_ref', '').startswith('Google C++ Style Guide: Comments') -->
| UID | Type | Status | Title |
|---|---|---|---|
| SR-0051 | system_requirement | approved | Use // comments, and /* */ only for blocks |
| SR-0052 | system_requirement | approved | Begin each file with a copyright and description comment |
| SR-0053 | system_requirement | approved | Comment each class's purpose and invariants |
| SR-0054 | system_requirement | approved | Comment what a function does, its parameters and side effects |
| SR-0055 | system_requirement | approved | Comment tricky or non-obvious variables |
| SR-0056 | system_requirement | approved | Explain why in implementation comments, not what |
| SR-0057 | system_requirement | approved | Mark unfinished work with a TODO and a reference |
| SR-0051 | system_requirement | proposed | Use // comments, and /* */ only for blocks |
| SR-0052 | system_requirement | proposed | Begin each file with a copyright and description comment |
| SR-0053 | system_requirement | proposed | Comment each class's purpose and invariants |
| SR-0054 | system_requirement | proposed | Comment what a function does, its parameters and side effects |
| SR-0055 | system_requirement | proposed | Comment tricky or non-obvious variables |
| SR-0056 | system_requirement | proposed | Explain why in implementation comments, not what |
| SR-0057 | system_requirement | proposed | Mark unfinished work with a TODO and a reference |
<!-- tl:end -->

## Formatting

<!-- tl:item UR-0009 -->
**UR-0009 — Formatting** — `user_requirement`, status `approved`
**UR-0009 — Formatting** — `user_requirement`, status `proposed`

> Rules governing line length, indentation, the layout of declarations, calls, conditionals, loops, pointers, classes and whitespace.

Expand All @@ -230,15 +230,15 @@ It carries
<!-- tl:table type == 'system_requirement' and attrs.get('source_ref', '').startswith('Google C++ Style Guide: Formatting') -->
| UID | Type | Status | Title |
|---|---|---|---|
| SR-0058 | system_requirement | approved | Keep lines within eighty characters |
| SR-0059 | system_requirement | approved | Indent with two spaces and never tabs |
| SR-0060 | system_requirement | approved | Avoid non-ASCII characters in source |
| SR-0061 | system_requirement | approved | Attach the opening brace to conditionals, loops and switches |
| SR-0062 | system_requirement | approved | Attach * and & to the type in pointer and reference expressions |
| SR-0063 | system_requirement | approved | Place |
| SR-0064 | system_requirement | approved | Lay out a class by visibility with two-space indentation |
| SR-0065 | system_requirement | approved | Do not indent the contents of a namespace |
| SR-0066 | system_requirement | approved | Use single spaces around binary operators and after keywords |
| SR-0067 | system_requirement | approved | Separate logical sections with single blank lines |
| SR-0058 | system_requirement | proposed | Keep lines within eighty characters |
| SR-0059 | system_requirement | proposed | Indent with two spaces and never tabs |
| SR-0060 | system_requirement | proposed | Avoid non-ASCII characters in source |
| SR-0061 | system_requirement | proposed | Attach the opening brace to conditionals, loops and switches |
| SR-0062 | system_requirement | proposed | Attach * and & to the type in pointer and reference expressions |
| SR-0063 | system_requirement | proposed | Place |
| SR-0064 | system_requirement | proposed | Lay out a class by visibility with two-space indentation |
| SR-0065 | system_requirement | proposed | Do not indent the contents of a namespace |
| SR-0066 | system_requirement | proposed | Use single spaces around binary operators and after keywords |
| SR-0067 | system_requirement | proposed | Separate logical sections with single blank lines |
<!-- tl:end -->

6 changes: 6 additions & 0 deletions throughline.toml
Original file line number Diff line number Diff line change
Expand Up @@ -60,3 +60,9 @@ ratified = "ratified"
invalidated = "rejected"
suspect = "suspect"
tombstone = "deleted"

[rules]
# This graph is published unsigned: its items are offered as they stand and are
# not ratified by a named person, so the gate does not ask for signatures here
# (the rule `unratified`). Every other rule stays on.
unratified = "off"
Loading