Re: [squid-dev] RFC: Class section/member _order_
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 < rouss...@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@lists.squid-cache.org > http://lists.squid-cache.org/listinfo/squid-dev > -- @mobile ___ squid-dev mailing list squid-dev@lists.squid-cache.org http://lists.squid-cache.org/listinfo/squid-dev
[squid-dev] RFC: Class section/member _order_
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@lists.squid-cache.org http://lists.squid-cache.org/listinfo/squid-dev
[squid-dev] RFC: Class section/member order
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
