AX Principle 2 requires comments to show correct usage patterns.
errMissingHMAC and errIntegrityViolation are tlvError sentinels (comparable
values), so the examples should use == not errors.Is from the banned errors
package.
Co-Authored-By: Charon <charon@lethean.io>
Three comments on Path, Exists, and Delete restated what the signatures
already convey. Replaced with concrete call examples per AX 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 function's
prose description; replaced with a concrete call site example.
Co-Authored-By: Charon <charon@lethean.io>
GenerateChallenge, SignChallenge, and VerifyChallenge had comments that
restated what the type signature already says. Replaced with concrete call
examples showing how each function is used in the handshake flow (AX §2).
Co-Authored-By: Charon <charon@lethean.io>
AX-2 violation: usage examples belong at the declaration site, not
scattered inside function bodies. The errIntegrityViolation usage hint
was already present at the variable declaration (line 17) and was
duplicated inside ReadAndVerify, creating noise in the implementation.
Co-Authored-By: Charon <charon@lethean.io>
AX Principle 2: comments show HOW with real values, not WHAT the name
already says. The old comment restated the variable name; the new comment
shows a concrete ReplaceAllString call with input and expected output.
Co-Authored-By: Charon <charon@lethean.io>
RFC-CORE-008 §2: comments that restate type signatures add zero information.
Replace the five prose comments (type-level + three field-level) with a single
concrete construction example showing real values.
Co-Authored-By: Charon <charon@lethean.io>
AX Principle 1 — predictable names over short names. Comments showing
usage examples must use the same full names as the implementation:
'buffer' not 'buf'.
Co-Authored-By: Charon <charon@lethean.io>
AX principle 2: comments show HOW with real values, not what the
signature already says. "startTask starts a single supervised task."
adds zero information — replaced with a concrete call site example.
Co-Authored-By: Charon <charon@lethean.io>
AX Principle 2: comments show usage, not prose descriptions of what the code
does. The two inline comments in ReadAndVerify described buffer reconstruction
in words rather than showing a call — deleted per RFC-025 §2.
Co-Authored-By: Charon <charon@lethean.io>
AX principle 2: comments show HOW with real values, not what the
signature already says. Replace "creates a new miner manager" prose
with a concrete call-site example showing manager lifecycle.
Co-Authored-By: Charon <charon@lethean.io>
AX Principle 1 — predictable names over short names. 'result' does not
describe what it holds; 'encodedTLV' names the TLV-encoded byte slice
exactly, matching the function under test.
Co-Authored-By: Charon <charon@lethean.io>
Remove the banned `fmt` import from mining.go; all fmt.Errorf calls in
Config.Validate replaced with the existing ErrInvalidConfig helper which
returns a structured *MiningError — consistent with the package error model.
Co-Authored-By: Charon <charon@lethean.io>
TagHMAC and TagPayload had inline prose comments ("The Signature",
"The Data") that restated what the names already convey. Replace
with concrete call-site examples per AX 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 prose "creates an encrypted bundle containing a mining
profile" restates the type signature — deleted in favour of a concrete call.
Co-Authored-By: Charon <charon@lethean.io>
AX Principle 1: predictable names over short names. The generic
local variable `value` required surrounding context to understand;
`tagValue` is self-documenting at every read site in the switch.
Co-Authored-By: Charon <charon@lethean.io>
AX Principle 2: comments must show HOW with real values, not restate the
type signature in prose. The previous comments added zero information.
Co-Authored-By: Charon <charon@lethean.io>
Single-letter variable `l` violates AX Principle 1 (predictable names
over short names) — renamed to `listener` to match the semantic intent.
Co-Authored-By: Charon <charon@lethean.io>
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>
