RFC-CORE-008 Principle 2 — comments must show HOW with real values,
not restate what the type signature already says.
Co-Authored-By: Charon <charon@lethean.io>
Test names encode intent — prose descriptions add zero information.
Per AX-2: if comment restates the signature, delete it.
Co-Authored-By: Charon <charon@lethean.io>
SetAuthMode, GetAuthMode, AllowPublicKey, and RevokePublicKey all had
comments that restated the function signature rather than showing concrete
usage. Replaced with call-site examples per AX Principle 2.
Co-Authored-By: Charon <charon@lethean.io>
AX Principle 1 — predictable names over short names. `cfg` requires
context to decode; `configuration` is self-describing.
Co-Authored-By: Charon <charon@lethean.io>
AX Principle 2: comments as usage examples. Both functions had prose descriptions
that restated the signature ("loads the miners configuration from the file system").
Replace with concrete call-site examples that show how to use the return value.
Co-Authored-By: Charon <charon@lethean.io>
Line 715 contained "// Example usage inside a connection handler" with no
code following it — a prose description stub with no usage example. This
violates AX Principle 2 (comments must show concrete usage with real values,
not describe intent in prose).
Co-Authored-By: Charon <charon@lethean.io>
AX Principle 2: comments that restate the type signature add zero information.
Replace with a concrete usage example showing how the return value is used.
Co-Authored-By: Charon <charon@lethean.io>
RawConfig.UnmarshalJSON used errors.New() (banned import) despite the
package already providing ErrInternal() for exactly this purpose.
Co-Authored-By: Charon <charon@lethean.io>
Replace fmt.Sprintf calls with string concatenation throughout
all MiningError constructors and the Error() method.
Co-Authored-By: Charon <charon@lethean.io>
AX Principle 2: comments show HOW with real values, not WHAT the
signature already states. "GetPeer returns a peer by ID" restates
the function name — replaced with a concrete call pattern.
Co-Authored-By: Charon <charon@lethean.io>
AX principle 2: comments show HOW with real values, not WHAT the
signature already says. The previous comment restated the return
type contract; replaced with a concrete call-site example.
Co-Authored-By: Charon <charon@lethean.io>
AX Principle 2 — comments show HOW with real values, not what the
signature already says. "returns true if the error is a ProtocolError"
restates the type; a concrete call pattern teaches agents how to use it.
Co-Authored-By: Charon <charon@lethean.io>
AX Principle 2: comments show HOW with real values, not WHAT the signature
already says. "GetType returns the miner type identifier" restates the
signature — replace with concrete call examples.
Co-Authored-By: Charon <charon@lethean.io>
TestConvenienceFunctions violated AX Principle 1 (predictable names — "ConvenienceFunctions"
is a vague label, not a description of what is tested) and Principle 10 (test naming must
follow TestFilename_Function_{Good,Bad,Ugly}).
Renamed to TestProtocol_DefaultHandler_Good, added a usage-example doc comment per
Principle 2.
Co-Authored-By: Charon <charon@lethean.io>
AX Principle 2: comments must show usage, not restate the signature.
"Clear clears the log buffer." adds zero information beyond the name.
Co-Authored-By: Charon <charon@lethean.io>
AX Principle 1: ch is an opaque abbreviation for a response channel — rename
to channel so the variable's role is predictable without tracing the map type.
AX Principle 2: "handleResponse processes incoming messages…" restates the
signature. Replaced with a concrete usage example showing how it is wired.
Co-Authored-By: Charon <charon@lethean.io>
AX Principle 1: predictable names over short names. The usage example
comment used the banned abbreviation `cfg` — replaced with `configuration`.
Co-Authored-By: Charon <charon@lethean.io>
Package-level regexp.MustCompile panics at startup on invalid pattern —
the Must* form explicitly banned by AX RFC-025 §6 (no hidden panics).
Move pattern to a const and compile via regexp.Compile inside the function.
Co-Authored-By: Charon <charon@lethean.io>
AX Principle 2 — comments must be usage examples, not prose descriptions.
The leading "verifies a well-formed signed frame" line restated the test
name without adding information; the usage example below it was sufficient.
Co-Authored-By: Charon <charon@lethean.io>
HasIdentity, GetIdentity, and GenerateIdentity had comments that
restated the type signature rather than showing concrete call patterns.
Replaced with AX-compliant usage examples per RFC-025 Principle 2.
Co-Authored-By: Charon <charon@lethean.io>
AX Principle 2: comments show HOW with real values, not WHAT the type
signature already says. "Send sends an encrypted message over the
connection." adds zero information.
Co-Authored-By: Charon <charon@lethean.io>
Seven setter/getter comments restated the function signature rather than
showing a concrete call (AX Principle 2). Replaced all with real invocation
examples so agents know exactly how to call each method.
Co-Authored-By: Charon <charon@lethean.io>
All private handler function comments restated what the function name
already said (AX Principle 2 violation). Replaced with concrete call
examples showing how each handler is invoked.
Co-Authored-By: Charon <charon@lethean.io>
AX Principle 1: predictable names over short names.
`opts` and `opt` are abbreviations — `options` and `option` are unambiguous.
Co-Authored-By: Charon <charon@lethean.io>
The comment was a duplicate of errTLVValueTooLarge's example.
Fixed to show how tlvError defines new sentinels.
Co-Authored-By: Charon <charon@lethean.io>
AX Principle 2: comments show HOW with real values, not WHAT the
signature already says. "processes incoming messages and returns a
response" restates the signature; the usage example shows how
HandleMessage is wired up via RegisterWithTransport.
Co-Authored-By: Charon <charon@lethean.io>
Four exported methods on TaskSupervisor had comments restating the
signature (AX §2 violation). Replaced with concrete call-site examples.
Co-Authored-By: Charon <charon@lethean.io>
Replace fmt.Errorf with a local testErr type to eliminate the banned
fmt import. The type carries its own usage example comment per AX
Principle 2.
Co-Authored-By: Charon <charon@lethean.io>
AX Principle 2 — comments as usage examples, not prose descriptions.
DefaultCircuitBreakerConfig, NewCircuitBreaker, State, Reset, GetCached
all had comments that restated the signature; replaced with concrete call examples.
Co-Authored-By: Charon <charon@lethean.io>
ProtocolError and ResponseHandler had prose descriptions restating
their names — AX Principle 2 violation. Replaced with concrete call
examples showing how callers use each type.
Co-Authored-By: Charon <charon@lethean.io>
Closure parameters in UninstallMiner and updateMinerConfig used the
abbreviated name cfg instead of configuration, violating AX Principle 1
(predictable names over short names).
Co-Authored-By: Charon <charon@lethean.io>
All four exported function comments in ratelimiter.go were prose
descriptions that restate the signature (AX Principle 2 violation).
Replaced with concrete usage examples showing realistic call sites.
Co-Authored-By: Charon <charon@lethean.io>
ConnectedPeers() had a comment that restated the function name ("returns
the number of connected peers"), violating AX Principle 2. Replaced with
a concrete usage example showing the guard pattern.
Co-Authored-By: Charon <charon@lethean.io>
errMissingHMAC and errIntegrityViolation comments were prose
descriptions. Replaced with errors.Is() usage patterns.
Co-Authored-By: Charon <charon@lethean.io>
AX Principle 2: comments that restate the type signature add zero information.
Nine accessor methods converted from "Foo returns the bar" to concrete call examples.
Co-Authored-By: Charon <charon@lethean.io>
Dimension weights are never reassigned — declaring them as mutable vars
implies changeability that does not exist. Const declares what IS (AX §5).
Co-Authored-By: Charon <charon@lethean.io>
`fn` is a single-letter abbreviation — AX principle 1 requires predictable
names over short names. `modifier` describes the parameter's role clearly.
Comment updated to a usage example per principle 2.
Co-Authored-By: Charon <charon@lethean.io>
AX Principle 2 — comments show HOW with real values, not WHAT the
signature already says. The old comment restated the method name;
the new comment shows the exact call pattern used in transport.go.
Co-Authored-By: Charon <charon@lethean.io>
All public API comments on ProfileManager restated the type signature in
prose — violating AX principle 2 (comments as usage examples). Replaced
with concrete call examples showing realistic values.
Co-Authored-By: Charon <charon@lethean.io>
