[squid-dev] RFC: Class section/member _order_

[Alex Rousskov]

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.
P.S. This is my Nth attempt to get through the mailing list filter. You 
may have received a pretty much the same message as an attachment to the 
previous mailing list post. Sorry about the noise!