AX Principle 2: comments that restate the type signature add zero
information. Replaced all prose-description comments on PeerRegistry
methods with concrete call-site examples that show real usage.
Co-Authored-By: Charon <charon@lethean.io>
AX Principle 2 — comments must show HOW with real values, not restate
what the type signature already says. The Container struct comment and
Initialize method comment both described what the code does in prose;
replaced with concrete call-site examples.
Co-Authored-By: Charon <charon@lethean.io>
AX Principle 2 — comments must show HOW with real values, not restate
the signature in prose. "GetRemoteLogs requests console logs from a
remote miner" added zero information; replaced with a concrete call
showing peerID, minerName, lines, and result handling.
Co-Authored-By: Charon <charon@lethean.io>
AX-2: comments must show HOW with real values, not restate the signature.
"ParsePayload unmarshals the payload into the given struct" adds zero
information. Replaced with a concrete call showing the pattern callers
actually use throughout this package.
Co-Authored-By: Charon <charon@lethean.io>
AX Principle 2: comments must show HOW with real values, not restate what
the type signature already says. Replaced description prose with a concrete
call pattern showing ctx + Config.
Co-Authored-By: Charon <charon@lethean.io>
AX Principle 2: comments restate the signature — replace with a concrete
call showing realistic values and the debounce behaviour as a note.
Co-Authored-By: Charon <charon@lethean.io>
AX Principle 1 — Predictable Names Over Short Names: `length` and
`lengthByte` are too generic for the TLV parsing context. Renamed to
`tagLength` and `tagLengthByte` so the variable names are
self-describing at read time.
Co-Authored-By: Charon <charon@lethean.io>
AX Principle 2: "If a comment restates what the type signature already says,
delete it." The "Store for processing" comment above the switch statement added
no information — the switch itself communicates that action.
Co-Authored-By: Charon <charon@lethean.io>
AX Principle 2: comments show HOW with real values, not WHAT the function does.
"checks if a public key is in the allowlist" restates the signature — replaced
with a concrete call example.
Co-Authored-By: Charon <charon@lethean.io>
TestPacket_MarshalAndSign_Ugly commented "modifying any byte breaks HMAC
verification" (prose description) but never called ReadAndVerify to prove it.
Replaced with a usage-example comment and an actual ReadAndVerify call that
asserts errIntegrityViolation is returned — AX Principle 2.
Co-Authored-By: Charon <charon@lethean.io>
AX Principle 1: predictable names over short names. `wg` requires
domain knowledge to decode; `waitGroup` is self-documenting.
Co-Authored-By: Charon <charon@lethean.io>
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>
