Code that explains itself.

Proposal 02 · Working title · Open for community review

A new builder should not have to start from zero.

Someone joins your project. It may be a developer, another team, an AI assistant, or you returning after months away. They open a file. Before changing it, they need to understand what it does, why it exists, where it runs and what depends on it.

That understanding should travel with the work. The TAGII Code Documentation Standard proposes a shared way to make the purpose and relationships of a system visible inside its files, then connect those files back to the architecture and its decisions.

Open any file. Understand its place. Follow its connections. Build with the person who comes next in mind.

Communication is part of the architecture.

A useful file header is an entry point, not the whole explanation. It identifies the file, its role, its version and its home. Inside the file, documentation follows the journey of the data: what comes in, what changes, what leaves, and what happens when a dependency fails.

The goal is to bring communication, education and understanding into the way we build software. A project should teach a newcomer how to work within it without making them reconstruct every decision from a conversation they never saw.

What and why

The file’s responsibility and the problem that made it necessary.

Where and how

Its place in the project, its deployment role and the way it carries out its task.

Connections

Who calls it, what it calls, what data crosses each boundary and what a response means.

Decisions and failures

The reasoning behind important choices, the alternatives considered, and the safe response when something breaks.

History and evidence

A version and links to the decisions, changes and executed checks that explain the current behaviour.

From one file to the whole system.

Consider a file that receives a request and saves a record. Its header points to the service it belongs to. Its function notes explain the accepted input and possible errors. A connection comment names the storage boundary and the information crossing it. A decision link explains why that storage approach was chosen. Tests check that a valid request succeeds and an invalid one is refused.

Following those links should lead a new builder through the system. Documentation becomes something they can navigate, question and maintain alongside the code.

What it looks like inside a project.

// FILE TYPE: Go package
// PATH: services/receipts/save.go
// VERSION: 1.2.0
// WHAT: Validate and store a receipt.
// WHY: Keep the original and its provenance together.
// HOW: Validate → authorize → store → acknowledge.
// CONNECTS TO: Receipt API; document store; audit log.
// WHERE (DEPLOYMENT): receipts-service
//   Source: services/receipts/save.go
//   Deploy: /srv/example/receipts/save.go
//   Runtime: receipts-service
// RECOVERY: Preserve the working revision before replacement.
// EVIDENCE: Link the transfer receipt and verification result.
// SECRETS: References only; never values.

// FLOW: Authorized request → validated receipt → storage
// ERROR: Reject malformed input before writing.
// DECISION: Keep the original bytes; record derived metadata.

The destination travels with the file.

A transfer tool can read a declared destination instead of asking someone to reconstruct the folder path. TAGII’s existing documentation tooling and mesh deployment command provide the starting point for that workflow. The target must still be a verified device and an allowed location.

1. Read the route. Identify the source, target device, deployment path and expected runtime from the documented file and deployment rules.
2. Preserve what works. Record the existing destination’s version and checksum, and create a recoverable backup before replacing it.
3. Transfer and compare. Send to the verified destination, read the result back and compare the intended bytes.
4. Keep the receipt. Record the original path, new path, checks and exact recovery location alongside the change.

The required behaviour is to stop when a target is missing, ambiguous or unauthorized, rather than guess a folder. A header alone does not guarantee this: backup, routing and verification must be enforced and tested through the actual tool. This proposal does not claim that every existing uploader already enforces the full sequence.

Written for people. Useful to AI.

AI can generate code quickly. It can also continue from an incorrect assumption about a dependency, deployment or earlier decision. Explicit context gives both people and AI something concrete to check before changing the system.

The proposed benefits are faster orientation, cleaner handovers and less drift between intent and implementation. They need measurement: comments can be wrong, generated descriptions can invent reasons, and a complete header does not prove the code works.

A practical starting point.

1. Choose one real change and document the files it touches.
2. Describe responsibilities, data flow, dependencies and failure behaviour in plain language.
3. Link the file to existing architecture and decision records. Keep secrets out of comments.
4. Ask a builder unfamiliar with the project to trace the change using that information.
5. Test the behaviour, correct misleading documentation and keep both current in review.

The standard and its tools.

This proposal grows from the existing TAGII Code Documentation Standard and its accompanying documentation tools. TAGII Upload Mesh is the related product; the proposal here is about how we write and structure code. TAGII Link is the separate device-connectivity add-on.

The existing standard covers file headers, sections, public functions, external calls, data flow, decisions, warnings and errors. Automation can check structure and help maintain links. People still need to explain intent and verify behaviour.

Help improve the standard.

Try it with your own team or project. Where does it help someone understand a system? Where does it create repetition? Which facts can be verified automatically, and which need a human explanation? Share examples, failure cases and improvements. The aim is a useful shared practice that builders can adopt and challenge.