mirror of
https://github.com/agent-substrate/substrate.git
synced 2026-11-10 10:13:50 +08:00
Haven Xia
2ef2c5ead8
An initial version of code convention guide for human and agents. - [x] Tests pass - [x] Appropriate changes to documentation are included in the PR
47 lines
1.9 KiB
Markdown
47 lines
1.9 KiB
Markdown
# Code Style Guide
|
|
|
|
Go conventions for this repository — written for humans and coding agents
|
|
alike. The [API style guide](api-style-guide.md) governs the proto surface;
|
|
this document governs the Go code behind it. Repository layout is covered by
|
|
[code layout](dev/code-layout.md).
|
|
|
|
The baseline is [Effective Go](https://go.dev/doc/effective_go), the
|
|
[Google Go style guide](https://google.github.io/styleguide/go/), and `gofmt`.
|
|
This document records only decisions that are specific to this project.
|
|
|
|
## Proto field access: check presence, don't default it
|
|
|
|
Generated getters (e.g. `req.GetActor().GetName()`) return zero values when any
|
|
message in the chain is nil. That is convenient and dangerous: a required
|
|
message the caller forgot to set silently becomes `""`, and the bug surfaces
|
|
far from its cause.
|
|
|
|
- A getter chain must never stand in for a presence check. Whenever a field
|
|
is required at this point in the code, check it explicitly and fail loudly:
|
|
`INVALID_ARGUMENT` at the API boundary, a real error (not a guessed zero
|
|
value) elsewhere.
|
|
- Once the boundary has validated presence, getters downstream are fine, as is
|
|
the guarded form for optional messages:
|
|
|
|
```go
|
|
if wass := worker.Assignment; wass != nil {
|
|
// Fields of wass were validated on write; use them directly.
|
|
}
|
|
```
|
|
|
|
- Absence of a group of fields that are set and cleared together is
|
|
represented by a nil message (`worker.Assignment == nil`), never by probing
|
|
a scalar field inside it for its zero value.
|
|
|
|
## Testing
|
|
|
|
- Standard library `testing` only — no assertion or mocking frameworks.
|
|
- Table-driven tests with `t.Run` subtests are the default shape.
|
|
- Prefer a real fake when one exists: `miniredis` for the store, `envtest` for
|
|
the Kubernetes API. Release resources with `t.Cleanup`.
|
|
|
|
## TODOs
|
|
|
|
Deferred decisions are recorded in code as `TODO(<issue-number>): ...`, placed where
|
|
the decision will eventually have to be made.
|