Spam detection software, running on the system "master.squid-cache.org",
has identified this incoming email as possible spam. The original
message has been attached to this so you can view it or label
similar future email. If you have any questions, see
the administrator of that system for details.
Content preview: Hello, Amos and I disagreed[1] regarding the existing
guidelines
for section/member order in C++ class declarations. To resolve that
disagreement,
this email proposes the order for future use. -----
Content analysis details: (105.0 points, 5.0 required)
pts rule name description
---- ---------------------- --------------------------------------------------
105 SQUID_ML_SPAM_01 No description available.
0.0 UNPARSEABLE_RELAY Informational: message has unparseable relay
lines
-0.0 T_SCC_BODY_TEXT_LINE No description available.
--- Begin Message ---
Hello,
Amos and I disagreed[1] regarding the existing guidelines for
section/member order in C++ class declarations. To resolve that
disagreement, this email proposes the order for future use.
-----
1. Class "sections" order (by member access specifiers): public,
protected, private. Each section, if present, declared once. Omit
sections that would be empty. Rationale: List most commonly reused, most
important things fist. In this context, those are public class
interfaces. The private section is the least important implementation
detail as far as the notion of a C++ class is concerned.
2. Within each section, the recommended member order is defined below.
Rationale: Group similar things together to facilitate searching and
highlight differences. List things most likely to be reused (by other
class members) and most important/influential things higher.
* friendship declarations
* type and aliases declarations; nested classes/structs/unions
* static member functions
* constructors and assignment operators
* destructors (just one until C++20)
* other/regular non-static member functions except overrides
* overrides (see item 3 below)
* static data members
* non-static data members
3. Overrides are a special case where we do not expect member
descriptions but do expect a reference to the corresponding API as
sketched below. Overrides are grouped by the (direct or indirect) parent
that _introduced_ the corresponding API method(s) (i.e. the parent class
that declared the virtual method but could _not_ use an override keyword
in that declaration). Rationale: Provide API context and facilitate
searching for member descriptions without chasing overrides through parents.
/* Baz API */
overrides for Baz-introduced methods (excluding destructors)
/* Bar API */
overrides for Bar-introduced methods (excluding destructors)
4. Caveats
The above rules are not meant to force authors to include any access
specifiers or members that the code does not actually need (except the
"private" specifier should be mentioned explicitly in class declarations
that have only private members -- do not rely on the class default
access specifier being "private").
Squid has some legacy code that forces CBDATA-related declarations to be
hoisted to the very top of the class, into the "unnamed" section. This
is an exception to the above rules. Eventually, we will stop doing that,
but we should continue doing that for consistency sake until the
offending CBDATA macros are gone.
Like any style rules, these rules are not comprehensive. If your use
case is not explicitly covered, then look around for similar Squid code
and try to be consistent and/or reasonable.
-----
Most of the above rules are arbitrary but common in the industry[2,3].
[1] https://github.com/squid-cache/squid/pull/1067#discussion_r889864925
[2] https://stackoverflow.com/q/308581
[3] https://google.github.io/styleguide/cppguide.html#Declaration_Order
HTH,
Alex.
--- End Message ---
_______________________________________________
squid-dev mailing list
squid-dev@lists.squid-cache.org
http://lists.squid-cache.org/listinfo/squid-dev
