From b2ec2e0d9f784cd5df837299ed5ad2f340368074 Mon Sep 17 00:00:00 2001 From: Henry Grech-Cini Date: Sat, 14 Nov 2026 13:34:52 +0000 Subject: [PATCH] Published unsigned: the gate does not ask this graph for signatures Since throughline 5.1 tl check --strict fails on every item no person has signed. This standard is published for others to use and is not signed, so the rule unratified is turned off here, with the reason beside it; every other rule stays on. docs/spec.md is regenerated: the status each item is shown in had gone stale behind the failing check. Co-Authored-By: Claude Fable 5.2 --- docs/spec.md | 154 +++++++++++++++++++++++------------------------ throughline.toml | 6 ++ 2 files changed, 83 insertions(+), 77 deletions(-) diff --git a/docs/spec.md b/docs/spec.md index 186815f..d606c9a 100644 --- a/docs/spec.md +++ b/docs/spec.md @@ -15,7 +15,7 @@ It carries ## Purpose -**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. @@ -25,7 +25,7 @@ It carries ## Header Files -**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. @@ -37,18 +37,18 @@ It carries | 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 | ## Scoping -**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. @@ -60,18 +60,18 @@ It carries | 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 | ## Classes -**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. @@ -83,21 +83,21 @@ It carries | 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 | ## Functions -**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. @@ -109,17 +109,17 @@ It carries | 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 | ## Ownership and Smart Pointers -**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. @@ -131,15 +131,15 @@ It carries | 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 | ## Other C++ Features -**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. @@ -151,25 +151,25 @@ It carries | 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 | -| 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 | +| 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 | ## Naming -**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. @@ -181,20 +181,20 @@ It carries | 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 | ## Comments -**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. @@ -206,19 +206,19 @@ It carries | 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 | ## Formatting -**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. @@ -230,15 +230,15 @@ It carries | 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 | diff --git a/throughline.toml b/throughline.toml index 42446ad..e4c3b9d 100644 --- a/throughline.toml +++ b/throughline.toml @@ -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"