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

[Francesco Chemolli]

Hi,
  I generally agree on the proposal. Any difference in opinion I have  is
trivial and not worth discussing

Regarding the ML filter, thanks for letting me know. I’ll have to figure
out what keyword triggered the anti spam filter

Francesco

On Thu, 23 Jun 2022 at 15:37, Alex Rousskov <
rousskov at measurement-factory.com> wrote:

> 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!
> _______________________________________________
> squid-dev mailing list
> squid-dev at lists.squid-cache.org
> http://lists.squid-cache.org/listinfo/squid-dev
>
-- 
@mobile
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.squid-cache.org/pipermail/squid-dev/attachments/20220623/c6cbf312/attachment.htm>