HUMAN: A quality principle for REFCODES 5.0.0

The preparations for REFCODES 5.0.0 have involved considerably more than adding functionality, because code which works still needs to be understood, questioned and maintained by people. Architectural recordings, runtime diagnostics, repeated audits and the simplification of public interfaces address different parts of this requirement, but share a common intention: Keeping software within human reach even when an increasing part of its implementation is produced in collaboration with Artificial Intelligence (AI).

During these preparations, the same questions kept returning in otherwise quite different modules. Does this type represent a useful concept or merely delegate to another type? Why does an application repeat behavior which belongs in a library? Can somebody use the public interface without first learning its implementation, and what evidence supports the claim that a refactoring preserved the intended behavior?

Such questions concern more than formatting or the number of lines in a method, because a neatly formatted implementation can still distribute one responsibility across too many places, hide important assumptions or leave its readers dependent upon an explanation which exists only in a conversation with its author. The recurring work therefore deserves a common name which describes the quality being sought rather than the tool used to produce the code.

Giving the common intention a name

The name HUMAN is introduced here for a quality principle expressed as Human Understandable, Maintainable, Accessible and Navigable:

H – Human: An inexperienced developer should be able to work with the code, …
U – Understandable: … comprehend the code and reason about it, …
M – Maintainable: … apply patches and extensions to the code …
A – Accessible: … without having to cope with a high cognitive load …
N – Navigable: … and easily locate code of importance and interest.

The human is the person who needs to use, inspect, verify or change the software, whether that person is its original author, a colleague or an ambitious hobbyist encountering the project for the first time.

AI generates code. HUMAN defines quality.

The distinction is intentional: A coding agent can implement changes and assist with reviews, but the quality expected of the result should not depend upon which model, provider or development environment happened to produce it. The same expectations apply to handwritten code, while replacing an agent should not require replacing the project’s understanding of quality.

Part	Meaning within `HUMAN`
Human	People remain the intended readers, users and maintainers of the code, with responsibility for deciding whether its behavior is appropriate.
Understandable	Concepts, responsibilities and contracts can be explained from the code and its documentation rather than guessed from implementation details.
Maintainable	A change has an identifiable owner, its effects can be assessed and relevant behavior can be verified without maintaining several copies of the same rule.
Accessible	The common use case can be approached through a small public interface, sensible defaults and an executable example, without requiring specialist knowledge of the internals.
Navigable	A reader can find the responsible abstraction, follow its relationships and connect the implementation with its documentation, tests and available runtime evidence.

This is a project-defined quality philosophy, not a claim to have invented understandable code or a new software-engineering paradigm. Established practices such as encapsulation, separation of responsibilities and testing already contribute to it, while the name makes their shared human purpose explicit and gives reviews a consistent point of reference.

Concepts before implementations

Understanding begins with recognizing what the software is about, which is why the REFCODES conventions give domain concepts priority over incidental technologies. A meaningful type brings together the values, rules and behavior belonging to a concept, so that its users do not have to reconstruct that relationship from strings, maps or repeated parameter combinations.

This connects directly with the principle of Self-Containedness, under which operations within a domain model produce valid results belonging to that domain. When the model owns its rules and the relationships between its concepts remain explicit, understanding an operation requires less knowledge of external orchestration and scattered validation. Within HUMAN, this is one way to make the code understandable and maintainable, rather than a requirement to turn every primitive value into another class.

Natural symmetry supports the same goal, because learning how an encoder is configured should help when approaching its decoder, just as understanding how a resource is opened should make its completion and ownership rules easier to discover. Shared interfaces and the focused contracts provided by refcodes-mixin can express genuine common capabilities, but a familiar method signature alone is not sufficient reason to treat two different responsibilities as the same concept.

Simplification without losing meaning

The familiar Keep It Simple, Stupid (KISS) principle becomes useful here when simplicity is measured by the concepts and decisions a reader must understand, rather than by the number of source files. Removing a helper which only forwards a call may make the design clearer, while merging several coherent types into one large multipurpose class may do exactly the opposite despite reducing that count.

The audits therefore look for duplicated validation, conversions and lifecycle handling, but also question factories, decorators and interfaces which do not represent a real boundary or choice. A common superclass is useful when it owns genuinely shared behavior, composition may be clearer when it does not, and similar enumerations should become one type only when their values carry the same domain meaning. This keeps consolidation from replacing several small problems with an abstraction which nobody can explain without listing its exceptions.

Unexplained numbers and copied symbols create a related burden, because the reader has to guess whether a value expresses a protocol requirement, a configurable default or an incidental layout choice. Named constants belong with the responsibility which gives them meaning, and genuinely shared symbols can have a common owner, while two unrelated values do not become one concept merely because both happen to be 12.

The same distinction matters in tests: A test for a configurable display symbol can refer to its owning constant while independently checking geometry and behavior, whereas a test for an externally specified protocol value needs an independent expectation. Repeating the implementation’s calculation inside an assertion would preserve the appearance of verification without providing much evidence that the calculation is correct.

An API an ambitious hobbyist can approach

An Application Programming Interface (API) is accessible in the sense of HUMAN when its ordinary use does not require a tour through the machinery behind it. A short example should lead from the relevant dependency to a successful operation, with advanced configuration remaining optional and obligations such as resource ownership, cancellation or threading explained where the caller needs to act on them.

The application helpers provide a concrete example of this direction. A command and its declarative argument syntax can be reused for a command line, an interactive prompt, a terminal form or a graphical form, while the selected presentation supplies the appropriate integration. The caller should not have to introduce a second parser or rewrite the business operation merely to make it available through a different interface.

The introductory examples in refcodes-archetype exercise this through public interfaces, and representative examples are compiled as independent consumers with their documented modules and without unused presentation toolkits.¹ This checks a different promise from an internal unit test: That the small recipe presented to a reader actually works outside the library’s own implementation environment.

Passing that check does not establish that an example is easy to understand, which still requires somebody to read it without silently supplying the author’s missing knowledge. The applications in FUNCODES provide practical consumers for these interfaces, exposing caller burdens which can remain unnoticed when a library is exercised only through its own tests.

Understanding the state of a running system

Readable source code describes how a system may behave, but does not by itself explain the effective configuration or state of a particular running instance. The refcodes-diagnosable module addresses this through explicit runtime self-description, allowing a component to expose a structured view of the state relevant to understanding it.

The resulting Schema, a structured description of values and their relationships, remains independent of the notation used to present it. The Diagnosable interface supplies this contract, while the schema infrastructure can represent the result as a document or diagram. An options decorator, for example, can describe an effective value together with its source, registered default and external configuration names, helping to explain why the running system uses that value rather than the one a reader expected.

This is deliberately not an automatic dump of every object in memory, because a diagnostic view needs meaningful boundaries and the component decides what it exposes. The separation also matters for maintainability: A component which describes its current state does not thereby need to take responsibility for recording execution histories or selecting a rendering technology.

Verifying how components collaborate

A different question arises when the intended architecture makes a claim about execution, such as requiring validation before a newly constructed information graph is published. The refcodes-diagnostics module addresses this by recording selected observations and evaluating them against explicit architectural rules, rather than relying upon a convincing explanation of what the code ought to do.

An architectural question is represented by a Concern, and a reusable instrumentation point which contributes evidence is a Sensor. The collected evidence forms a Recording, an immutable view of an observed execution flow which can be evaluated through assertions and rendered as a diagram. The architecture tests in SERVPHER, for example, check the order of scanning, generation, processing, validation and publication, while sequence diagrams make the observed collaboration visible.

The assertions and diagrams consume the same Recording, and events received directly or reconstructed from logs are interpreted by the same reconstruction mechanism. This avoids maintaining separate explanations of the architecture for different consumers of the evidence, connecting verification with the consolidation already sought in ordinary application code.

The boundary of that evidence remains important: An assertion says something about the selected scenario, its instrumentation and the rule being evaluated, not about every possible execution of the system. Together with functional tests, static checks and human review, architectural recordings make behavior inspectable without turning a successful test or an attractive diagram into a claim of complete correctness.

Navigability is more than having a convenient folder structure, because a reader needs a path from an observed behavior or requirement to the concept responsible for it, and from there to its contract, implementation and verification. Consistent names, directed module dependencies, linked documentation and focused tests all contribute to that path, while an unexplained delegation chain or an important decision left only in a chat makes it harder to follow.

The shared contribution conventions in AGENTS.md and the review procedure in AUDITS.md make these expectations available beyond any particular conversation or coding agent.² They ask recurring questions about semantic ownership, symmetry, public interfaces, consolidation, failure paths and affected consumers, so that a change is examined against the project’s rules rather than accepted because its author describes it confidently.

An audit finding needs a concrete location, an observable problem and a proportionate correction, and the correction needs relevant verification. A successful build is useful evidence, but does not establish that all hardware behavior, rendering effects or unexplored failure paths have been checked, so the remaining boundaries need to stay visible alongside the result.

REFCODES 5.0.0 as HUMAN software

In the sense defined here, the upcoming REFCODES 5.0.0 is HUMAN software: Its quality philosophy combines explicit domain concepts and reusable contracts with approachable entry points, runtime self-description, architectural evidence and a maintained review process. This classification describes the standards applied to the project and the mechanisms supporting them, rather than an independently awarded certificate or a declaration that every public interface has reached its final form.

The distinction makes the classification useful instead of ceremonial, because a newly discovered duplication, an inaccessible example or an unexplained runtime behavior remains something to investigate rather than something a label can excuse. A change can improve one aspect while weakening another, and the question is whether its overall effect leaves people better able to use, understand and verify the system.

None of the particular mechanisms described here is mandatory for applying the principle elsewhere. Another project may use different languages, diagnostic tools or review procedures, and handwritten software is subject to the same expectations, because HUMAN describes the qualities of the result rather than prescribing a REFCODES dependency or a particular way of generating it.

Conclusion

The work towards REFCODES 5.0.0 has brought together activities which initially appeared separate, from removing redundant types and naming constants to making effective runtime state visible and architectural claims executable. Their common purpose is to preserve a codebase which people can approach and continue to maintain without depending upon the memory of its author or the assurances of the agent which helped produce it.

The principle of HUMAN gives that purpose a name without pretending that software can be made understandable by naming a principle. Its practical value lies in the decisions, public interfaces, explanations and verifiable evidence which remain when the implementation conversation has ended and somebody else needs to work with the result.

HUMAN: A quality principle for REFCODES 5.0.0

Categories

Tags