`tag` is not in the accepted single-letter exception list (i, _, t, c).
`tagByte` is self-describing: the byte value of the TLV tag field.
Co-Authored-By: Charon <charon@lethean.io>
AX Principle 1 — predictable names over short names. Test comments showing
writeTLV usage had buf (abbreviated) while the actual code used buffer
(descriptive). Comments are usage examples that agents learn from; the name
must match what an agent would write.
Co-Authored-By: Charon <charon@lethean.io>
AX Principle 2 — comments show HOW with real values, not what the
signature already says. Prose restating the method signature deleted;
concrete call examples with realistic miner names substituted.
Co-Authored-By: Charon <charon@lethean.io>
MAC is an abbreviation requiring context; expectedMessageAuthCode matches
the established messageAuthCode pattern and is self-describing (AX §1).
Co-Authored-By: Charon <charon@lethean.io>
AX-1 (Predictable Names): abbreviated field names require mental mapping.
mutex and saveMutex are self-describing; mu and saveMu are not.
Co-Authored-By: Charon <charon@lethean.io>
AX Principle 1 — predictable names over short/non-standard names.
errorA and errorB are not ecosystem-standard; err is the correct
name for error variables. Each call now checks err immediately after
capture, matching the established Go and Core convention.
Co-Authored-By: Charon <charon@lethean.io>
Three internal method comments restated what the function name already
expressed (AX Principle 2). Replaced with concrete call-site examples
that show how each method is used in context.
Co-Authored-By: Charon <charon@lethean.io>
Comment was teaching agents to use the banned errors package.
Direct sentinel comparison (err == errTLVValueTooLarge) is correct.
Co-Authored-By: Charon <charon@lethean.io>
Abbreviated field name `mu` violated AX Principle 1 (predictable names over
short names). Renamed to `mutex` to match the convention already used in the
sibling `PeerRateLimiter` struct in the same file.
Co-Authored-By: Charon <charon@lethean.io>
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>
