Raised from a review comment on #730, declined there because it is a tree-wide
question rather than one parameter.
docs/NAMING.md states the Tier 3 this-pointer rule as:
base when the declared type is the abstract base struct, self otherwise.
Three concrete writer classes name it descriptively instead:
| Function |
First parameter |
SolidSyslogSdElement_Begin / _Param / _End |
element |
SolidSyslogSdValue_String / _Uint32 / … |
value |
SolidSyslogHeaderField_PrintUsAscii / _Uint32 |
field |
They are consistent with each other and inconsistent with the stated rule, so
this is not drift in one place — it is a rule written with vtable-dispatched
roles in mind, applied to a family that has no base struct to distinguish from.
The decision
Two coherent outcomes, and either is fine as long as it is chosen:
- Rename the family to
self, making the rule literal everywhere. Touches
three headers and their sources, mechanical, no behaviour change.
- Narrow the rule to say
self is required where a class has an abstract
base to be distinguished from, and a descriptive name is acceptable for a
concrete writer that never dispatches. NAMING.md already reserves both self
and base tree-wide, so nothing else is at risk from allowing a third name.
Worth noting the second is not merely the cheaper option: element, value and
field read better at their call sites than three identical selfs would, in
code whose whole job is that the author can see what they are writing into.
Not urgent, and not a defect — but a stated rule that the code does not follow is
the shape that let the platform naming drift far enough to need a rename, so it
should not just sit.
Raised from a review comment on #730, declined there because it is a tree-wide
question rather than one parameter.
docs/NAMING.mdstates the Tier 3 this-pointer rule as:Three concrete writer classes name it descriptively instead:
SolidSyslogSdElement_Begin/_Param/_EndelementSolidSyslogSdValue_String/_Uint32/ …valueSolidSyslogHeaderField_PrintUsAscii/_Uint32fieldThey are consistent with each other and inconsistent with the stated rule, so
this is not drift in one place — it is a rule written with vtable-dispatched
roles in mind, applied to a family that has no base struct to distinguish from.
The decision
Two coherent outcomes, and either is fine as long as it is chosen:
self, making the rule literal everywhere. Touchesthree headers and their sources, mechanical, no behaviour change.
selfis required where a class has an abstractbase to be distinguished from, and a descriptive name is acceptable for a
concrete writer that never dispatches.
NAMING.mdalready reserves bothselfand
basetree-wide, so nothing else is at risk from allowing a third name.Worth noting the second is not merely the cheaper option:
element,valueandfieldread better at their call sites than three identicalselfs would, incode whose whole job is that the author can see what they are writing into.
Not urgent, and not a defect — but a stated rule that the code does not follow is
the shape that let the platform naming drift far enough to need a rename, so it
should not just sit.