State first
Describe the state before and after an instruction. This makes hidden assumptions about initialization, ownership, and persistence easier to notice.
Builder notes
Programs, accounts, and state
Developer documentation becomes easier when code, accounts, instructions, and transactions are kept distinct. Each concept answers a different question about how an application behaves.
This guide is written as a mental model for reading documentation, not as a substitute for version-specific references or testing in an appropriate environment.
Browse guidesA small mental model
| Concept | Question | Useful reading cue |
|---|---|---|
| Program | What rules can execute? | Read the interface, constraints, and upgrade model. |
| Account | Where is data stored? | Check ownership, layout, and permissions. |
| Instruction | What action is requested? | Follow inputs and expected state changes. |
| Transaction | How are requests packaged? | Review signers, ordering, fees, and final status. |
Reading a new repository
- Start with the README and identify the supported runtime and version.
- Locate the public entry points and inspect the types passed into them.
- Trace account ownership and determine which values are created or modified.
- Read tests for expected failures, boundary values, and permission checks.
- Run a small local experiment only after understanding the documented assumptions.
“Good developer documentation does not remove complexity; it places each dependency where a reader can inspect it.”
Errors matter
An error path is part of the interface. Record which input caused it, whether state changed, and whether a retry is meaningful.
Version context
Package versions, runtime versions, and network configuration can alter behavior. Record them beside examples so later readers can reproduce the reasoning.
Decision guide for a code change
- Does the change alter account layout or only presentation?
- Does it add a signer, permission, external dependency, or new data path?
- What happens when an account is missing, stale, or owned by another program?
- Which tests demonstrate the intended behavior and the expected failure?
These questions turn a broad code review into a sequence of smaller checks. They also give future maintainers a record of why a design was selected.
Source-aware building
Use official references for exact APIs, inspect release notes before changing versions, and keep examples neutral about outcomes. Wridian presents concepts for learning rather than a deployment guarantee.