Skip to content

Commit cf304b2

Browse files
committed
Added a "no new globals" rule
1 parent ad33e4e commit cf304b2

1 file changed

Lines changed: 43 additions & 0 deletions

File tree

docs/DeveloperResources/SquidCodingGuidelines.md

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,10 +53,53 @@ formater.
5353
4. use `= default` declaration whenever possible if it is
5454
sufficient and `= delete` declaration when method is
5555
prohibited.
56+
* Avoid adding new globals as detailed in the section below.
5657
* Naming conventions as covered in
5758
[Features/SourceLayout](/Features/SourceLayout)
5859
are to be used.
5960

61+
### Rule: No new globals
62+
63+
C++ globals are prone to several [initialization order-related
64+
problems](https://isocpp.org/wiki/faq/ctors#static-init-order). In most cases,
65+
globals are unnecessary. Unnecessary globals should not be added to Squid. In
66+
most cases, an unnecessary global Foo of type Type should be replaced with the
67+
following wrapper function:
68+
69+
```C++
70+
auto &
71+
Foo()
72+
{
73+
static const auto foo = new Type(...);
74+
return *foo;
75+
}
76+
```
77+
78+
The function may be marked static, become a class member, adjusted to return a
79+
constant reference, and/or contain more complex object initialization code, as
80+
needed.
81+
82+
The increased performance cost of accessing an object through a function
83+
wrapper (as opposed to direct access to a global object) is _not_ a valid
84+
excuse for avoiding a global.
85+
86+
This rule applies to all objects that are (or may become) susceptible to
87+
initialization order problems, including globals in the global namespace,
88+
namespace-scope globals, and class-scope static members (regardless of their
89+
access modifiers). This rule does not apply to function-scoped variables.
90+
91+
This rule *does* apply to would-be globals of built-in/intrinsic types because
92+
they may be subject to similar [initialization
93+
problems](https://isocpp.org/wiki/faq/ctors#static-init-order-on-intrinsics).
94+
95+
To avoid [deinitialization order
96+
problems](https://isocpp.org/wiki/faq/ctors#construct-on-first-use-v2), the
97+
wrapper function must dynamically allocate the would-be global to prevent its
98+
destruction. In very rare cases where the global must be destructed at the end
99+
of the program, a [Nifty
100+
Counter](https://isocpp.org/wiki/faq/ctors#nifty-counter-idiom) may be used
101+
instead of the wrapper function.
102+
60103
## Suggested coding rules
61104

62105
* Use internally consistent naming scheme (see below for choices).

0 commit comments

Comments
 (0)