12. AttributeIO and AttributeIORef Naming Convention#

Date: 2026-03-12

Status#

Accepted

Context#

The AttributeIO and AttributeIORef classes introduced in ADR9 have descriptive, unambiguous names that clearly communicate their role within fastcs. However, their length leads to verbose class names when drivers subclass them:

class TempControllerAttributeIO(AttributeIO[float, TempControllerIORef]): ...
class TempControllerIORef(AttributeIORef): ...

Alternative names were considered but none offered a meaningful improvement:

  • Shorter names (e.g. IO, Ref) are too terse in isolation and lose the context that these are attribute-scoped constructs within fastcs.

  • Alternative descriptive names introduce new terminology without reducing confusion.

The verbosity is felt most in driver code, where developers repeatedly type the full parent class name. In the fastcs internals and documentation, the full names remain appropriate.

Decision#

The AttributeIO and AttributeIORef class names are retained unchanged. Driver authors are encouraged to introduce shorter driver-specific aliases by subclassing:

class MyIO(AttributeIO[float, MyRef]): ...
class MyRef(AttributeIORef): ...

The subclass name is left to the driver author’s discretion. The inheritance relationship ensures the full fastcs name (AttributeIO, AttributeIORef) remains visible in the class hierarchy and in documentation, preserving discoverability for anyone unfamiliar with the driver.

Consequences#

  • Driver code is less verbose without sacrificing clarity at the fastcs API level.

  • The parent class is always visible via IDE tooling, so developers encountering a short name like MyRef can immediately understand its role by inspecting the inheritance.

  • Over time, as developers become more familiar with the pattern, informal shorthand (“the IO”, “the Ref”) is expected to emerge in discussions to make this less of an issue.