Skip to content

chore: the this-pointer naming rule and the concrete writer classes disagree #738

Description

@DavidCozens

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    choreMaintenance, tooling, and infrastructure

    Type

    No type

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions