├── .github └── ISSUE_TEMPLATE │ ├── config.yml │ └── core-issue-template.md ├── README.md └── wording-guidelines.md /.github/ISSUE_TEMPLATE/config.yml: -------------------------------------------------------------------------------- 1 | blank_issues_enabled: false 2 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # CWG (Core Working Group) 2 | 3 | This repository hosts an experimental issue tracker for prospective core issues. 4 | 5 | Please consult the existing core issues list at 6 | http://www.open-std.org/jtc1/sc22/wg21/ prior to submitting an issue. 7 | 8 | When submitting an issues, please provide a description in the style 9 | of the existing issues and, if possible, provide a suggested 10 | resolution. 11 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/core-issue-template.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Core issue template 3 | about: Template for requesting creation of a core issue 4 | title: "[section.label] Proposed issue title" 5 | labels: '' 6 | assignees: '' 7 | 8 | --- 9 | 10 | Full name of submitter (unless configured in github; will be published with the issue): 11 | 12 | Reference (section label): 13 | 14 | Link to reflector thread (if any): 15 | 16 | Issue description: 17 | 18 | Suggested resolution: 19 | -------------------------------------------------------------------------------- /wording-guidelines.md: -------------------------------------------------------------------------------- 1 | # Wording Guidelines 2 | 3 | Jens Maurer et al., 2025-03-02 4 | 5 | This document offers a collection of guidelines for writing wording 6 | targeted at integration into the ISO C++ Working Draft, 7 | with a focus on core language wording (clauses 2-15). 8 | The target audience is paper authors proposing changes to 9 | the ISO C++ Working Draft. 10 | 11 | These are guidelines, not hard-and-fast rules. 12 | Sometimes, the subject matter is conducive to deviating from these guidelines. 13 | 14 | ## General 15 | 16 | Read clause 4 [intro] of the Working Draft. 17 | It provides the general framework for all detailed technical specifications. 18 | 19 | The C++ Working Draft in its present form is 20 | the result of more than 30 years of ongoing collaborative effort, 21 | with changes being applied at least twice per year. 22 | The existing wording thus varies in quality. 23 | In general, newer wording better addresses the present expectations on 24 | rigor and clarity than older wording. 25 | 26 | Having an implementation of a new feature is great, 27 | but does not imply that the specification is easy or 28 | that the feature is easily implementable in other implementations. 29 | Listen to implementers that utter concerns; 30 | the target environments for implementations vary a lot. 31 | 32 | Further reading: 33 | - [ISO/IEC Directives, Part 2](https://www.iso.org/sites/directives/current/part2/index.xhtml) 34 | - [Style guidelines for the Working Draft](https://github.com/cplusplus/draft/wiki/Specification-Style-Guidelines) 35 | 36 | 37 | ## Presentation 38 | 39 | The purpose of suggested wording in your paper is to convey 40 | the changes intended to be made to the Working Draft 41 | to the wording review groups (CWG and LWG) and to the editors. 42 | Specify the published version of the Working Draft (N-paper) your 43 | changes are based on. 44 | Specify any dependencies on other papers 45 | that need to be applied before yours makes sense. 46 | 47 | ### Changes 48 | 49 | In your paper, precede each chunk of wording with an introductory 50 | sentence indicating where the words apply (section number and/or 51 | stable label plus paragraph number). 52 | Present wording as differences 53 | (green underlined text for additions, red strikethrough text for deletions) 54 | relative to the existing text in the working draft. 55 | Quote sufficient context so that the editors can readily apply the changes 56 | even when paragraph or section numbers have shifted; 57 | a sentence or a bullet usually suffices for that. 58 | 59 | The wording sections should be indented relative to the introductory 60 | sentences. The granularity of the differences should be the word; do 61 | not try to present clever single-character changes. 62 | 63 | Do not bother with numbering notes or examples; those will be 64 | auto-numbered in the Working Draft anyway. 65 | 66 | **Example** 67 | 68 | > Modify [expr.shift] paragraph 3 as follows: 69 | > > The value of `E1 >> E2` is E1/2E2, 70 | > > rounded down towards negative infinity. 71 | 72 | (GitHub does not render colors.) 73 | 74 | ### Font styles 75 | 76 | Use an approximation of the font styles used in the Working Draft. 77 | In the interest of efficiency, 78 | unchanged quoted text can ignore font variations. 79 | 80 | - The defining appearance of a term or phrase is in *italics*; 81 | other mentions are in regular font. 82 | - Grammar non-terminals (e.g. _declarator-id_) are in *italics* everywhere. 83 | 84 | ## Structure 85 | 86 | When adding a feature to the core language, 87 | do not attempt to add a single subclause 88 | that specifies the entirety of the feature. 89 | Instead, start with the existing subclauses and 90 | determine where updates are needed. 91 | 92 | **Example:** 93 | [basic.scope] covers all kinds of scopes, 94 | [basic.lookup] specifies name lookup, and 95 | [expr.prim.id] establishes the meaning of names 96 | (in some cases, even when appearing outside of expressions). 97 | 98 | Use math-like abstract concepts such as pairs (a bundle of two 99 | things), tuples (a bundle of multiple things), sets (an unordered 100 | collection of things), or lists (an ordered collection of things) as 101 | necessary to convey a rule as precisely as possible. 102 | 103 | Consider introducing definitions of terms and phrases to manage complexity. 104 | Add cross-references when using a term or phrase 105 | that could be mistaken as having the ordinary English meaning. 106 | Within a single paragraph, 107 | have at most one cross-reference to any given subclause. 108 | 109 | Clearly differentiate definitions from normative rules, 110 | for example by having them in separate sentences. 111 | 112 | It is acceptable to introduce hypothetical C++ entities 113 | such as types (e.g. closure types) or templates, 114 | but all salient properties of such must be clearly specified. 115 | For grammar non-terminals such as template-head, 116 | the hypothetical definition is expected to have a valid token representation; 117 | otherwise, 118 | the abstract concept needs to be divorced from the grammar non-terminal 119 | (see "exception specification" vs. _exception-specification_). 120 | 121 | In library wording, 122 | when specifying a complex component (e.g. RCU or hazard pointers), 123 | spend a few paragraphs of introductory wording 124 | to describe the data structure in the abstract, 125 | possibly defining terms and phrases as necessary, and 126 | then refer to the abstract description 127 | in the specification of the individual classes and member functions. 128 | 129 | ### Notes, examples, and footnotes 130 | 131 | Notes present statements of fact. 132 | Use notes to highlight subtle consequences of the normative rules 133 | and/or introduce cross-references to other parts of the standard. 134 | Nesting an example inside a note is fine. 135 | ISO disallows modal verbs such as "shall" or "may", 136 | with the exception of "can", in notes. 137 | Do not introduce normative rules in notes. 138 | When referring to rules defined normatively elsewhere, 139 | paraphrase the rule instead of trying to be precise; shorter is better. 140 | Notes must be correct, but they need not be exhaustive. 141 | 142 | **Example:** 143 | > [ Note: The one-definition rule ([basic.def.odr]) prohibits X. -- end note]" 144 | 145 | This adds a desirable cross-reference to the definition of the technical term; 146 | the formulation does not preclude that the ODR also prohibits A, B, C beyond X. 147 | 148 | Footnotes present ancillary information, establishing context beyond 149 | the C++ Standard, such as trademark hints. 150 | They should appear rarely. 151 | 152 | Add examples to the Working Draft text. 153 | Do not spend more than one example on basic syntactic exposition, 154 | but do show surprising outcomes and interactions with other rules. 155 | For syntax disambiguation rules, present an example of a tricky parse. 156 | 157 | Prefer normative requirements if possible; this increases portability. 158 | Sometimes, implementations cannot all provide a feature due to 159 | environmental limitations or other concerns, but the standard should 160 | still guide common implementations towards a desirable outcome. 161 | For that case, prefix a paragraph with "*Recommended practice:*" 162 | and use "should". 163 | 164 | **Example:** 165 | 166 | > *Recommended practice:* 167 | > Implementations should not emit a warning 168 | > that a name-independent declaration is used or unused. 169 | 170 | ### Conversions 171 | 172 | When adding a new conversion, also check overload resolution for a 173 | corresponding adjustment. 174 | 175 | ## Language 176 | 177 | Use grammatical English. 178 | Do not use contractions. 179 | Do not use "you". 180 | 181 | By default, use present tense and indicative form. 182 | 183 | Hyphenate compound adjectives, e.g. "volatile-qualified". 184 | Use the Oxford (or serial) comma. 185 | 186 | In the core language, 187 | "shall" is generally used to establish requirements on user programs: 188 | "X shall be green" means the program is ill-formed if X is not green. 189 | Exception: "The implementation shall ..." is a requirement on the implementation; 190 | violation means non-conformance of the implementation. 191 | 192 | In the standard library, "shall" establishes a precondition; 193 | when violated, the program has undefined behavior. 194 | 195 | Do not use "in" when nested constructs are not supposed to be in 196 | scope. 197 | 198 | **Example (bad):** 199 | > X shall not appear in the expression 200 | 201 | covers lambda bodies nested in the expression, which is often undesirable. 202 | 203 | Use a recursive definition of a term or phrase to clearly specify how 204 | a rule applies to a recursive construct such as an expression or 205 | block. 206 | 207 | Use "of" to uniquely identify top-level grammar components, without 208 | risk of unwanted recursion. 209 | 210 | **Example:** 211 | > The _nested-name-specifier_ of a _qualified-id_ ... 212 | 213 | does not cover any _nested-name-specifier_ nested 214 | within the top-level _nested-name-specifier_. 215 | 216 | 217 | ## Specific words and phrases 218 | 219 |
220 |
ill-formed, no diagnostic required
221 |
means that the standard does not 222 | specify anything about the behavior at all, i.e. the behavior for such 223 | a program is unbounded. 224 | Use this when requiring a diagnostic is a hardship for compilers, 225 | e.g. when different translation units are involved or 226 | when analysis of uninstantiated templates would be needed. 227 |
228 | 229 |
X is ill-formed
230 |
means the compiler is required to produce an error message for the program. 231 |
232 | 233 |
X is conditionally-supported
234 |
means that the program is ill-formed if an implementation does not support X
235 | 236 | 237 |
X is implementation-defined
238 |
means the implementation has freedom of choice, 239 | but is required to document its choice of behavior.
240 | 241 |
the behavior is undefined
242 |
means there are no restrictions on the 243 | program behavior if control flow reaches that particular point.
244 | 245 |
the behavior is erroneous
246 |
means the program may (or may not) terminate at any future time; 247 | the behavior in case of non-termination must be specified
248 | 249 |
it is unspecified whether X or Y
250 |
means either X or Y can validly 251 | happen, and each evaluation can make a different choice. 252 |
253 |
254 | 255 | Avoid unbounded unspecified behavior. 256 | 257 | **Example (bad):** 258 | 259 | > If X happens, the behavior of the program is unspecified. 260 | 261 | Do not try to make runtime behavior ill-formed; this is a category error. 262 | --------------------------------------------------------------------------------