go-documentation — independently scanned and version-tracked by SaferSkills.
SaferSkills independently audited go-documentation (Agent Skill) and scored it 100/100 (green). The audit ran 55 deterministic rules across Security, Supply Chain, Maintenance, Transparency, and Community; it found 0 high-severity and 0 lower-severity findings. The full rule-by-rule trace and per-finding evidence are below. Free, methodology-open.
Findings & checks · 0 flagged
Every scanned point with the score it earned and what moved between them.
First recorded scan — no prior version to compare against.
The primary manifest — the file an agent reads to learn what this artifact does.
Documentation in Go is part of the API. Doc comments compile into go doc, pkg.go.dev, and IDE tooltips, so the rules exist to make those views readable. Code says what; comments say why, when, and what can go wrong.
// Encode writes ...). Full sentences, capitalised, end with a period.Deprecated: paragraph.Example* functions in _test.go files with // Output: blocks are verified by go test.package clause in one file (doc.go if long).Detect this first — it changes the doc surface area.
| Signal | Project type | Docs to focus on |
|---|---|---|
No main package, intended to be imported | Library | godoc, Example* tests, README usage examples, pkg.go.dev rendering |
Has main package, cmd/ directory, ships a binary or Docker image | Application/CLI | Install instructions, --help text, config docs |
| Both (libraries that ship CLI tools) | Both | All of the above |
Universal: doc comments on exported names, package comment, README, LICENSE, CONTRIBUTING (recommended), CHANGELOG (recommended).
Read references/godoc-grammar.md for the comment grammar, headings/lists, deprecation markers, and full examples.
// Encode writes the JSON encoding of req to w.
// It returns an error if req contains a non-serialisable field.
func Encode(w io.Writer, req *Request) errorRules:
A, An, The) may precede the name.Unexported names with non-obvious behaviour should also be commented — those comments are for maintainers, not godoc.
| Topic | Document when | Skip when |
|---|---|---|
| Parameters | edge cases, units, ranges | type/name already say it |
| Context | behaviour differs from standard cancellation | standard ctx.Err() propagation |
| Concurrency | ambiguous (e.g., a read that mutates internal state) | read-only is safe by default; mutation is unsafe by default |
| Cleanup | always — defer Close(), Stop() requirements | — |
| Errors | sentinel values (ErrNotFound), error types (use *PathError pointer) | — |
| Named returns | multiple values of the same type | type alone is clear |
| Side effects | always — file writes, network calls, init-time work | — |
Restating signatures is the most common waste:
// Bad — restates what you can see
// SetName sets the name.
func (u *User) SetName(name string) { ... }
// Good — explains the why and the constraints
// SetName sets the user's display name. Returns ErrInvalidName
// if name is empty or longer than MaxNameLen.
func (u *User) SetName(name string) error { ... }Every package has exactly one. Place it above the package clause in one file. For long descriptions, use a dedicated doc.go.
// Package store provides a transactional key-value store backed by
// SQLite. It is safe for concurrent use; see (*Store).BeginTx for
// transaction semantics.
package storeFor main packages, use the binary name:
// The migrate command applies SQL migrations from disk to a database.
package mainfunc ExampleEncode() {
var buf bytes.Buffer
_ = Encode(&buf, &Request{ID: "abc"})
fmt.Println(buf.String())
// Output: {"id":"abc"}
}Naming:
func Example() — package-level example.func ExampleFoo() — example for Foo.func ExampleFoo_bar() — alternate example for Foo titled "bar".func ExampleT_Method() — example for T.Method.go test runs these and verifies the // Output: line matches. They appear in godoc attached to the named symbol — the best documentation is the kind the compiler keeps honest.
Read references/examples-and-readme.md for Example* patterns, the canonical README outline, and CONTRIBUTING/CHANGELOG templates.Sentinel errors: document on the variable, not on each return.
// ErrNotFound is returned when no record matches the query.
var ErrNotFound = errors.New("store: not found")Error types: document with the pointer form so errors.Is/errors.As examples match.
// PathError records the operation and path that caused an error.
// Use errors.As(err, new(*PathError)) to inspect the fields.
type PathError struct { Op, Path string; Err error }| Anti-pattern | Why it hurts | Do this instead |
|---|---|---|
// SetName sets the name. | restates signature, no value | explain constraints, side effects, errors |
// TODO: improve this with no owner/date | forever-todo | link to issue or remove |
// Note: this is fast. | unsupported claim | benchmark in test, link to it |
// Deprecated. (no body) | tooling reads the body | // Deprecated: use NewFoo instead. |
| Trailing period missing | inconsistent godoc layout | end every sentence with . |
| Multi-paragraph doc with no blank line | godoc collapses it | separate paragraphs with // blank lines |
| Documenting unexported names with godoc-style sentences | wastes effort; not rendered | one-line maintainer note is enough |
| Doc comment above the wrong symbol (blank line between) | godoc treats it as orphan | no blank line between comment and symbol |
go doc ./... renders cleanly for every package (no missing doc warnings from linters).Deprecated: paragraph.Example* test per non-trivial exported function in a library package.golangci-lint run --enable=godot,revive passes (revive's exported rule).Mechanical checks belong to CI:
revive exported — missing doc comments on exported names.godot — missing trailing periods in doc comments.misspell — typos in comments.go vet — basic format-string and other issues that also surface in docs.Example* tests, README outline, CONTRIBUTING/CHANGELOG--help~30 seconds. Free. No account. Every finding cites a rule and a line of evidence.