Mirrors/CppCoreGuidelines
1
0
Fork 0
mirror of https://github.com/isocpp/CppCoreGuidelines.git synced 2025-12-17 20:54:41 +03:00
Code Issues Actions Packages Projects Releases Wiki Activity

Merge pull request #318 from tkruse/fix-mdstyle-21

Browse Source 
fix minor style issues
This commit is contained in:
Gabriel Dos Reis
2015-10-13 09:07:31 -07:00
parent 6d9db03404 5d1d990cd9
commit 9ed3417f4b
1 changed files with 111 additions and 112 deletions
Download Patch File Download Diff File Expand all files Collapse all files

87
CppCoreGuidelines.md
View File

@@ -680,7 +680,7 @@ Avoid errors leading to (possibly unrecognized) wrong results.
const int n = 10; const int n = 10;
int a[n] = {}; int a[n] = {};
// ... // ...
increment1(a, m); // maybe typo, maybe m<=n is supposed increment1(a, m); // maybe typo, maybe m <= n is supposed
// but assume that m == 20 // but assume that m == 20
// ... // ...
} }
@@ -2345,7 +2345,7 @@ If you need the notion of an optional value, use a pointer, `std::optional`, or
##### Enforcement ##### Enforcement
* (Simple) ((Foundation)) Warn when a parameter being passed by value has a size greater than `4*sizeof(int)`. * (Simple) ((Foundation)) Warn when a parameter being passed by value has a size greater than `4 * sizeof(int)`.
Suggest using a `const` reference instead. Suggest using a `const` reference instead.
### <a name="Rf-T"></a> F.21: Use a `T` parameter for a small object ### <a name="Rf-T"></a> F.21: Use a `T` parameter for a small object
@@ -2365,7 +2365,7 @@ For small objects (up to two or three words) it is also faster than alternatives
##### Enforcement ##### Enforcement
* (Simple) ((Foundation)) Warn when a `const` parameter being passed by reference has a size less than `3*sizeof(int)`. Suggest passing by value instead. * (Simple) ((Foundation)) Warn when a `const` parameter being passed by reference has a size less than `3 * sizeof(int)`. Suggest passing by value instead.
### <a name="Rf-T-ref"></a> F.22: Use a `T&` for an in-out-parameter ### <a name="Rf-T-ref"></a> F.22: Use a `T&` for an in-out-parameter
@@ -5422,7 +5422,7 @@ This leaves us with three alternatives:
[Ddeclare such classes `struct` rather than `class`](#Rc-struct) [Ddeclare such classes `struct` rather than `class`](#Rc-struct)
* *All protected*: [Avoid `protected` data](#Rh-protected). * *All protected*: [Avoid `protected` data](#Rh-protected).
* *All private*: If you’re writing an type that maintains an invariant, then all the variables should be private – it should be encapsulated. * *All private*: If you’re writing an type that maintains an invariant, then all the variables should be private – it should be encapsulated.
This is the vast majority of classes. This is the vast majority of classes.
##### Example ##### Example
@@ -5671,7 +5671,7 @@ Consider:
cout << pb1->id(); // "B" cout << pb1->id(); // "B"
cout << pb2->id(); // "D" cout << pb2->id(); // "D"
if (pb1->id()==pb2->id()) // *pb1 is the same type as *pb2 if (pb1->id() == pb2->id()) // *pb1 is the same type as *pb2
if (pb2 == "D") { // looks innocent if (pb2 == "D") { // looks innocent
D* pd = static_cast<D*>(pb1); D* pd = static_cast<D*>(pb1);
// ... // ...
@@ -5679,7 +5679,7 @@ Consider:
// ... // ...
} }
The result of `pb2=="D"` is actually implementation defined. The result of `pb2 == "D"` is actually implementation defined.
We added it to warn of the dangers of home-brew RTTI. We added it to warn of the dangers of home-brew RTTI.
This code may work as expected for years, just to fail on a new machine, new compiler, or a new linker that does not unify character literals. This code may work as expected for years, just to fail on a new machine, new compiler, or a new linker that does not unify character literals.
@@ -5959,19 +5959,19 @@ To find function objects and functions defined in a separate namespace to "custo
##### Example ##### Example
Consider `swap`. It is a general (standard library) function with a definintion that will work for just about any type. Consider `swap`. It is a general (standard library) function with a definition that will work for just about any type.
However, it is desirable to define specific `swap()`s for specific types. However, it is desirable to define specific `swap()`s for specific types.
For example, the general `swap()` will copy the elements of two `vector`s being swapped, whereas a good specific implementation will not copy elements at all. For example, the general `swap()` will copy the elements of two `vector`s being swapped, whereas a good specific implementation will not copy elements at all.
namespace N { namespace N {
My_type X { /* ... */ }; My_type X { /* ... */ };
void swap(X&,X&); // optimized swap for N::X void swap(X&, X&); // optimized swap for N::X
// ... // ...
} }
void f1(N::X& a, N::X& b) void f1(N::X& a, N::X& b)
{ {
std::swap(a,b); // propably not what we wanted: calls std::swap() std::swap(a, b); // probably not what we wanted: calls std::swap()
} }
The `std::swap()` in `f1()` does exactly what we asked it to do: it calls the `swap()` in namespace `std`. The `std::swap()` in `f1()` does exactly what we asked it to do: it calls the `swap()` in namespace `std`.
@@ -5993,7 +5993,6 @@ This is done by including the general function in the lookup for the function:
swap(a,b); // calls N::swap if it exists, otherwise std::swap swap(a,b); // calls N::swap if it exists, otherwise std::swap
} }
##### Enforcement ##### Enforcement
Unlikely, except for known customization points, such as `swap`. Unlikely, except for known customization points, such as `swap`.
@@ -6102,7 +6101,7 @@ Macros do not obey scope and type rules.
##### Example ##### Example
First some bad old code First some bad old code:
// webcolors.h (third party header) // webcolors.h (third party header)
#define RED 0xFF0000 #define RED 0xFF0000
@@ -6115,12 +6114,12 @@ First some bad old code
#define PURPLE 1 #define PURPLE 1
#define BLUE 2 #define BLUE 2
int webby = BLUE; // webby==2; probably not what was desired int webby = BLUE; // webby == 2; probably not what was desired
instead use an `enum`: instead use an `enum`:
enum class Webcolor { red=0xFF0000, green=0x00FF00, blue=0x0000FF }; enum class Webcolor { red = 0xFF0000, green = 0x00FF00, blue = 0x0000FF };
enum class Productinfo { red=0, purple=1, blue=2 }; enum class Productinfo { red = 0, purple = 1, blue = 2 };
int webby = blue; // error: be specific int webby = blue; // error: be specific
Webcolor webby = Webcolor::blue; Webcolor webby = Webcolor::blue;
@@ -6137,7 +6136,7 @@ An enumeration shows the enumerators to be related and can be a named type
##### Example ##### Example
enum class Webcolor { red=0xFF0000, green=0x00FF00, blue=0x0000FF }; enum class Webcolor { red = 0xFF0000, green = 0x00FF00, blue = 0x0000FF };
##### Enforcement ##### Enforcement
@@ -6151,7 +6150,7 @@ To minimize surprises.
##### Example ##### Example
enum Webcolor { red=0xFF0000, green=0x00FF00, blue=0x0000FF }; enum Webcolor { red = 0xFF0000, green = 0x00FF00, blue = 0x0000FF };
enum Productinfo { red=0, purple=1, blue=2 }; enum Productinfo { red=0, purple=1, blue=2 };
int webby = blue; // error, ambiguous: be specific int webby = blue; // error, ambiguous: be specific
@@ -6807,7 +6806,7 @@ You could "temporarily share ownership simply by using another `stared_ptr`.)
##### Enforcement ##### Enforcement
???probably impossible. If we could statically detect cycles, we wouldn't need `weak_ptr` ??? probably impossible. If we could statically detect cycles, we wouldn't need `weak_ptr`
### <a name="Rr-smartptrparam"></a> R.30: Take smart pointers as parameters only to explicitly express lifetime semantics ### <a name="Rr-smartptrparam"></a> R.30: Take smart pointers as parameters only to explicitly express lifetime semantics
@@ -7114,7 +7113,7 @@ Statement rules:
* [ES.75: Avoid `do`-statements](#Res-do) * [ES.75: Avoid `do`-statements](#Res-do)
* [ES.76: Avoid `goto`](#Res-goto) * [ES.76: Avoid `goto`](#Res-goto)
* [ES.77: ??? `continue`](#Res-continue) * [ES.77: ??? `continue`](#Res-continue)
* [ES.78: Always end non-empty a `case` with a `break`](#Res-break) * [ES.78: Always end a non-empty `case` with a `break`](#Res-break)
* [ES.79: ??? `default`](#Res-default) * [ES.79: ??? `default`](#Res-default)
* [ES.85: Make empty statements visible](#Res-empty) * [ES.85: Make empty statements visible](#Res-empty)
@@ -7544,7 +7543,7 @@ This cannot trivially be rewritten to initialize `i` and `j` with initializers.
Note that for types with a default constructor, attempting to postpone initialization simply leads to a default initialization followed by an assignment. Note that for types with a default constructor, attempting to postpone initialization simply leads to a default initialization followed by an assignment.
A popular reason for such examples is "efficiency", but a compiler that can detect whether we made a used-before-set error can also eliminate any redundant double initialization. A popular reason for such examples is "efficiency", but a compiler that can detect whether we made a used-before-set error can also eliminate any redundant double initialization.
At the cost of repeating `cond` we could write At the cost of repeating `cond` we could write:
widget i = (cond) ? f1() : f3(); widget i = (cond) ? f1() : f3();
widget j = (cond) ? f2() : f4(); widget j = (cond) ? f2() : f4();
@@ -7617,7 +7616,7 @@ In the not uncommon case where the input target and the input operation get sepa
A good optimizer should know about input operations and eliminate the redundant operation. A good optimizer should know about input operations and eliminate the redundant operation.
##### Example: ##### Example
Using an `unitialized` value is a symptom of a problem and not a solution: Using an `unitialized` value is a symptom of a problem and not a solution:
@@ -7641,7 +7640,7 @@ Now the compiler cannot even simply detect a used-befor-set.
##### Note ##### Note
Sometimes, a lambda can be used as an initializer to avoid an uninitialized variable. Sometimes, a lambda can be used as an initializer to avoid an uninitialized variable:
error_code ec; error_code ec;
Value v = [&] { Value v = [&] {
@@ -7663,9 +7662,9 @@ or maybe:
##### Enforcement ##### Enforcement
* Flag every uninitialized variable. * Flag every uninitialized variable.
Don't flag variables of user-defined types with default constructors. Don't flag variables of user-defined types with default constructors.
* Check that an uninitialized buffer is written into *immediately* after declaration. * Check that an uninitialized buffer is written into *immediately* after declaration.
Passing a uninitialized variable as a non-`const` reference argument can be assumed to be a write into the variable. Passing a uninitialized variable as a non-`const` reference argument can be assumed to be a write into the variable.
### <a name="Res-introduce"></a> ES.21: Don't introduce a variable (or constant) before you need to use it ### <a name="Res-introduce"></a> ES.21: Don't introduce a variable (or constant) before you need to use it
@@ -8259,7 +8258,7 @@ This is an ad-hoc simulation of destructors. Declare your resources with handles
??? ???
### <a name="Res-break"></a> ES.78: Always end non-empty a `case` with a `break` ### <a name="Res-break"></a> ES.78: Always end a non-empty `case` with a `break`
##### Reason ##### Reason
@@ -8899,7 +8898,7 @@ this also applies to `%`.
# <a name="S-performance"></a> PER: Performance # <a name="S-performance"></a> PER: Performance
???should this section be in the main guide??? ??? should this section be in the main guide???
This section contains rules for people who needs high performance or low-latency. This section contains rules for people who needs high performance or low-latency.
That is, rules that relates to how to use as little time and as few resources as possible to achieve a task in a predictably short time. That is, rules that relates to how to use as little time and as few resources as possible to achieve a task in a predictably short time.
@@ -11491,10 +11490,10 @@ That subset can be compiled with both C and C++ compilers, and when compiled as
##### Example ##### Example
int* p1 = malloc(10*sizeof(int)); // not C++ int* p1 = malloc(10 * sizeof(int)); // not C++
int* p2 = static_cast<int*>(malloc(10*sizeof(int))); // not C, C-style C++ int* p2 = static_cast<int*>(malloc(10 * sizeof(int))); // not C, C-style C++
int* p3 = new int[10]; // not C int* p3 = new int[10]; // not C
int* p4 = (int*)malloc(10*sizeof(int)); // both C and C++ int* p4 = (int*)malloc(10 * sizeof(int)); // both C and C++
##### Enforcement ##### Enforcement
@@ -12144,7 +12143,7 @@ Use of these casts can violate type safety and cause the program to access a var
// ... // ...
use(99,*new Foo{1,2}); // not a Foobar use(99, *new Foo{1, 2}); // not a Foobar
If a class hierarchy isn't polymorphic, avoid casting. If a class hierarchy isn't polymorphic, avoid casting.
It is entirely unsafe. It is entirely unsafe.
@@ -13059,12 +13058,12 @@ It's verbose and only needed where C compatibility matters.
###### Note ###### Note
Even Dennis Ritchie deemed `void f(void)` an abomination. Even Dennis Ritchie deemed `void f(void)` an abomination.
You can make an argument for that abomination in C when function prototypes were rare so that banning You can make an argument for that abomination in C when function prototypes were rare so that banning:
int f(); int f();
f(1,2,"weird but valid C89"); // hope that f() is defined int f(a,b,c) char* c; { /* ... */ } f(1, 2, "weird but valid C89"); // hope that f() is defined int f(a, b, c) char* c; { /* ... */ }
would have cause major problems, but not in the 21st century and in C++. would have caused major problems, but not in the 21st century and in C++.
# <a name="S-faq"></a> FAQ: Answers to frequently asked questions # <a name="S-faq"></a> FAQ: Answers to frequently asked questions
@@ -13734,18 +13733,18 @@ When is a class a container? ???
# <a name="S-glossary"></a> Glossary # <a name="S-glossary"></a> Glossary
A relatively informal definition of twrms used in the guidelines A relatively informal definition of terms used in the guidelines
(based of the glossary in [Programming: Principles and Practice using C++](http://www.stroustrup.com/programming.html)) (based of the glossary in [Programming: Principles and Practice using C++](http://www.stroustrup.com/programming.html))
* *abstract*: class a class that cannot be directly used to create objects; often used to define an interface to derived classes. * *abstract class*: a class that cannot be directly used to create objects; often used to define an interface to derived classes.
A class is made abstract by having a pure virtual function or a protected constructor. A class is made abstract by having a pure virtual function or a protected constructor.
* *abstraction*: a description of something that selectively and deliberately ignores (hides) details (e.g., implementation details); selective ignorance. * *abstraction*: a description of something that selectively and deliberately ignores (hides) details (e.g., implementation details); selective ignorance.
* *address*: a value that allows us to find an object in a computer’s memory. * *address*: a value that allows us to find an object in a computer’s memory.
* *algorithm*: a procedure or formula for solving a problem; a finite series of computational steps to produce a result. * *algorithm*: a procedure or formula for solving a problem; a finite series of computational steps to produce a result.
* *alias*: an alternative way of referring to an object; often a name, pointer, or reference. * *alias*: an alternative way of referring to an object; often a name, pointer, or reference.
* *application*: a program or a collection of programs that is considered an entity by its users. * *application*: a program or a collection of programs that is considered an entity by its users.
* *approximation*: something (e.g., a value or a design) that is close to the perfect or ideal (value or design). * *approximation*: something (e.g., a value or a design) that is close to the perfect or ideal (value or design).
Often an approximation is a result of trade-offs among ideals. Often an approximation is a result of trade-offs among ideals.
* *argument*: a value passed to a function or a template, in which it is accessed through a parameter. * *argument*: a value passed to a function or a template, in which it is accessed through a parameter.
* *array*: a homogeneous sequence of elements, usually numbered, e.g., [0:max). * *array*: a homogeneous sequence of elements, usually numbered, e.g., [0:max).
* *assertion*: a statement inserted into a program to state (assert) that something must always be true at this point in the program. * *assertion*: a statement inserted into a program to state (assert) that something must always be true at this point in the program.
@@ -13757,20 +13756,20 @@ Often an approximation is a result of trade-offs among ideals.
* *code*: a program or a part of a program; ambiguously used for both source code and object code. * *code*: a program or a part of a program; ambiguously used for both source code and object code.
* *compiler*: a program that turns source code into object code. * *compiler*: a program that turns source code into object code.
* *complexity*: a hard-to-precisely-define notion or measure of the difficulty of constructing a solution to a problem or of the solution itself. * *complexity*: a hard-to-precisely-define notion or measure of the difficulty of constructing a solution to a problem or of the solution itself.
Sometimes complexity is used to (simply) mean an estimate of the number of operations needed to execute an algorithm. Sometimes complexity is used to (simply) mean an estimate of the number of operations needed to execute an algorithm.
* *computation*: the execution of some code, usually taking some input and producing some output. * *computation*: the execution of some code, usually taking some input and producing some output.
* *concept*: (1) a notion, and idea; (2) a set of requirements, usually for a template argument * *concept*: (1) a notion, and idea; (2) a set of requirements, usually for a template argument
* *concrete class*: class for which objects can be created. * *concrete class*: class for which objects can be created.
* *constant*: a value that cannot be changed (in a given scope); not mutable. * *constant*: a value that cannot be changed (in a given scope); not mutable.
* *constructor*: an operation that initializes (“constructs”) an object. * *constructor*: an operation that initializes (“constructs”) an object.
Typically a constructor establishes an invariant and often acquires resources needed for an object to be used (which are then typically released by a destructor). Typically a constructor establishes an invariant and often acquires resources needed for an object to be used (which are then typically released by a destructor).
* *container*: an object that holds elements (other objects). * *container*: an object that holds elements (other objects).
* *copy*: an operation that makes two object have values that compare equal. See also move. * *copy*: an operation that makes two object have values that compare equal. See also move.
* *correctness*: a program or a piece of a program is correct if it meets its specification. * *correctness*: a program or a piece of a program is correct if it meets its specification.
Unfortunately, a specification can be incomplete or inconsistent, or can fail to meet users’ reasonable expectations. Unfortunately, a specification can be incomplete or inconsistent, or can fail to meet users’ reasonable expectations.
Thus, to produce acceptable code, we sometimes have to do more than just follow the formal specification. Thus, to produce acceptable code, we sometimes have to do more than just follow the formal specification.
* *cost*: the expense (e.g., in programmer time, run time, or space) of producing a program or of executing it. * *cost*: the expense (e.g., in programmer time, run time, or space) of producing a program or of executing it.
Ideally, cost should be a function of complexity. Ideally, cost should be a function of complexity.
* *customisation point*: ??? * *customisation point*: ???
* *data*: values used in a computation. * *data*: values used in a computation.
* *debugging*: the act of searching for and removing errors from a program; usually far less systematic than testing. * *debugging*: the act of searching for and removing errors from a program; usually far less systematic than testing.
@@ -13788,17 +13787,17 @@ Simplified definition: a declaration that allocates memory.
* *floating-point number*: a computer’s approximation of a real number, such as 7.93 and 10.78e–3. * *floating-point number*: a computer’s approximation of a real number, such as 7.93 and 10.78e–3.
* *function*: a named unit of code that can be invoked (called) from different parts of a program; a logical unit of computation. * *function*: a named unit of code that can be invoked (called) from different parts of a program; a logical unit of computation.
* *generic programming*: a style of programming focused on the design and efficient implementation of algorithms. * *generic programming*: a style of programming focused on the design and efficient implementation of algorithms.
A generic algorithm will work for all argument types that meet its requirements. In C++, generic programming typically uses templates. A generic algorithm will work for all argument types that meet its requirements. In C++, generic programming typically uses templates.
* *Global variable*: Technically, a named object in namespace scope * *Global variable*: Technically, a named object in namespace scope
* *handle*: a class that allows access to another through a member pointer or reference. See also resource, copy, move. * *handle*: a class that allows access to another through a member pointer or reference. See also resource, copy, move.
* *header*: a file containing declarations used to share interfaces between parts of a program. * *header*: a file containing declarations used to share interfaces between parts of a program.
* *hiding*: the act of preventing a piece of information from being directly seen or accessed. * *hiding*: the act of preventing a piece of information from being directly seen or accessed.
For example, a name from a nested (inner) scope can prevent that same name from an outer (enclosing) scope from being directly used. For example, a name from a nested (inner) scope can prevent that same name from an outer (enclosing) scope from being directly used.
* *ideal*: the perfect version of something we are striving for. Usually we have to make trade-offs and settle for an approximation. * *ideal*: the perfect version of something we are striving for. Usually we have to make trade-offs and settle for an approximation.
* *implementation*: (1) the act of writing and testing code; (2) the code that implements a program. * *implementation*: (1) the act of writing and testing code; (2) the code that implements a program.
* *infinite loop*: a loop where the termination condition never becomes true. See iteration. * *infinite loop*: a loop where the termination condition never becomes true. See iteration.
* *infinite recursion*: a recursion that doesn’t end until the machine runs out of memory to hold the calls. * *infinite recursion*: a recursion that doesn’t end until the machine runs out of memory to hold the calls.
In reality, such recursion is never infinite but is terminated by some hardware error. In reality, such recursion is never infinite but is terminated by some hardware error.
* *information hiding*: the act of separating interface and implementation, thus hiding implementation details not meant for the user’s attention and providing an abstraction. * *information hiding*: the act of separating interface and implementation, thus hiding implementation details not meant for the user’s attention and providing an abstraction.
* *initialize*: giving an object its first (initial) value. * *initialize*: giving an object its first (initial) value.
* *input*: values used by a computation (e.g., function arguments and characters typed on a keyboard). * *input*: values used by a computation (e.g., function arguments and characters typed on a keyboard).