From cbbe6071cee067ea7ecd579ae59fc3c6991c7a56 Mon Sep 17 00:00:00 2001 From: mpherg Date: Thu, 31 Jan 2019 14:13:57 -0500 Subject: [PATCH] Standardize example and note headers (minor) (#1318) * Standardize example headings Some example headings used "Example, [good,bad]" and others used "Example; [good,bad]" (note the comma verses semicolon). The vast majority of the headings used the comma version, so this commit normalizes all example headings to use a comma instead of a semicolon. * Standardize note heading level Two of the "Note" headings were set to level four, but the rest are at level 5. Fix the level fours to make them level fives. --- CppCoreGuidelines.md | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/CppCoreGuidelines.md b/CppCoreGuidelines.md index c0f43d6..3fa6914 100644 --- a/CppCoreGuidelines.md +++ b/CppCoreGuidelines.md @@ -487,7 +487,7 @@ What is expressed in code has defined semantics and can (in principle) be checke The first declaration of `month` is explicit about returning a `Month` and about not modifying the state of the `Date` object. The second version leaves the reader guessing and opens more possibilities for uncaught bugs. -##### Example; bad +##### Example, bad This loop is a restricted form of `std::find`: @@ -506,7 +506,7 @@ This loop is a restricted form of `std::find`: // ... } -##### Example; good +##### Example, good A much clearer expression of intent would be: @@ -3717,7 +3717,7 @@ value) of any assignment operator. With guaranteed copy elision, it is now almost always a pessimization to expressly use `std::move` in a return statement. -##### Example; bad +##### Example, bad S f() { @@ -3725,7 +3725,7 @@ With guaranteed copy elision, it is now almost always a pessimization to express return std::move(result); } -##### Example; good +##### Example, good S f() { @@ -4196,11 +4196,11 @@ This is especially important for [overloaded operators](#Ro-namespace). Mixing a type definition and the definition of another entity in the same declaration is confusing and unnecessary. -##### Example; bad +##### Example, bad struct Data { /*...*/ } data{ /*...*/ }; -##### Example; good +##### Example, good struct Data { /*...*/ }; Data data{ /*...*/ }; @@ -6439,7 +6439,7 @@ Asymmetric treatment of operands is surprising and a source of errors where conv If a class has a failure state, like `double`'s `NaN`, there is a temptation to make a comparison against the failure state throw. The alternative is to make two failure states compare equal and any valid state compare false against the failure state. -#### Note +##### Note This rule applies to all the usual comparison operators: `!=`, `<`, `<=`, `>`, and `>=`. @@ -6488,7 +6488,7 @@ It is really hard to write a foolproof and useful `==` for a hierarchy. Of course there are ways of making `==` work in a hierarchy, but the naive approaches do not scale -#### Note +##### Note This rule applies to all the usual comparison operators: `!=`, `<`, `<=`, `>`, and `>=`. @@ -10150,11 +10150,11 @@ Check length of local and non-local names. Also take function length into accoun Code clarity and readability. Too-similar names slow down comprehension and increase the likelihood of error. -##### Example; bad +##### Example, bad if (readable(i1 + l1 + ol + o1 + o0 + ol + o1 + I0 + l0)) surprise(); -##### Example; bad +##### Example, bad Do not declare a non-type with the same name as a type in the same scope. This removes the need to disambiguate with a keyword such as `struct` or `enum`. It also removes a source of errors, as `struct X` can implicitly declare `X` if lookup fails. @@ -13134,14 +13134,14 @@ The result is undefined and probably a crash. This also applies to `%`. -##### Example; bad +##### Example, bad double divide(int a, int b) { // BAD, should be checked (e.g., in a precondition) return a / b; } -##### Example; good +##### Example, good double divide(int a, int b) { // good, address via precondition (and replace with contracts once C++ gets them) @@ -15110,7 +15110,7 @@ Sometimes C++ code allocates the `volatile` memory and shares it with "elsewhere static volatile long vl; please_use_this(&vl); // escape a reference to this to "elsewhere" (not C++) -##### Example; bad +##### Example, bad `volatile` local variables are nearly always wrong -- how can they be shared with other languages or hardware if they're ephemeral? The same applies almost as strongly to member variables, for the same reason. @@ -16206,7 +16206,7 @@ Note that function parameter is a local variable so changes to it are local. A member function should be marked `const` unless it changes the object's observable state. This gives a more precise statement of design intent, better readability, more errors caught by the compiler, and sometimes more optimization opportunities. -##### Example; bad +##### Example, bad class Point { int x, y;