Pixiv CLI Code Commenting

pixiv-cli Code Commenting

Expose information that names and structure cannot express clearly: caller contracts, intent, constraints, invariants, and meaningful workflow stages. Optimize understanding, not comment count or code length.

Repository context

Read root AGENTS.md and the affected owner before editing. This checked-in skill is self-contained; it does not require the personal code-commenting skill. Review caller contracts across CLI, SDK, and MCP without duplicating them in every layer. Keep machine-output, credential, transaction outcome, and Rust/cgo ownership comments precise; an ordinary prose cleanup must not change build directives or the cgo preamble. Use pixiv-cli-test for verification scope and pixiv-cli-develop for any authorized structural change.

Editing workflow

1. Read the affected symbol, enclosing flow, nearby comments, and applicable repository conventions. Inspect callers or tests when a claimed contract is unclear; do not infer thread safety, atomicity, retry safety, or ownership from a name.
2. Identify the missing information before adding prose. Keep accurate contract and intent comments, correct stale ones, and remove narration that adds no information. Leaving self-explanatory code uncommented is a valid outcome.
3. Choose the nearest useful location: API documentation for a caller contract, a type/field comment for an invariant or unit, an inline comment for a surprising choice, or numbered comments for a meaningful multi-stage flow.
4. Keep edits within the requested scope. A comment review is not permission to rename APIs, extract helpers, redesign modules, add tests, or introduce dependencies. Report structural or behavioral defects separately unless their correction is authorized.
5. Re-read comments against the final code and applicable documentation output. Confirm stage order, symbol references, factual guarantees, and protected directives. Report uncertain claims rather than documenting them as facts.

Language and syntax

• Accept either English or Chinese source comments; this skill's English instructions do not select a comment language. Follow the explicit task preference, otherwise the surrounding code and intended readers. Keep a coherent language within a comment; do not bulk-translate unrelated code or duplicate every comment bilingually.
• Preserve identifier spelling, protocol values, units, URLs, issue references, and required documentation tags. Natural-language freedom does not waive language-specific syntax.
• Use the repository's existing formatter and documentation conventions. For Go, place a doc comment directly before its declaration, normally start with the declared identifier (or Package name for a package), and use complete sentences. Chinese prose can follow the unchanged identifier.
• Document newly added or changed exported Go declarations and caller-visible field semantics. A concise, accurate contract is enough; avoid boilerplate headings and parameter lists that only repeat the signature. A private helper does not automatically need a doc comment.

Documentation comments

Describe only the caller-relevant facts that apply: observable behavior, preconditions, zero/nil/absent semantics, units or formats, ordering, side effects, ownership/lifetime, concurrency, cancellation, and error or partial-commit outcomes.

Give important structs and domain types their meaning and invariants. Document fields individually only when their meaning is not already clear from the type contract and names. Keep implementation walkthroughs out of API documentation.

For example, a useful contract states an ownership rule:

// Snapshot returns a copy of the current settings.
// The caller may modify the result without changing the store.

Use that wording only when the implementation actually provides a copy. Avoid vacuous prose such as Snapshot returns a snapshot, and do not promise guarantees that the code or accepted contract does not establish.

Keep a shared contract in its authoritative location and link or name it where helpful; do not copy long explanations into every caller.

Numbered workflow comments

Use // 1. ..., // 2. ..., and // 3. ... when stable, meaningful phases make an orchestration function easier to scan. Number phases, not statements; there is no mandatory number of stages, comments, or function length.

A useful outline reveals sequencing constraints rather than translating helper names. For a workflow that actually enforces these boundaries:

// 1. Validate the complete batch before any record becomes visible.
// 2. Recheck revisions under the transaction lock to avoid lost updates.
// 3. Publish the batch; report post-commit cleanup errors as committed.

Place each comment immediately before its actual block, not as a detached table of contents. Use the native comment syntax in languages other than Go.

• Keep stages at one abstraction level with parallel action wording and sequential numbering. Renumber after reordering, insertion, or deletion.
• Prefer a flat sequence. Nested numbering is justified only by a real nested workflow that benefits from navigation, not by nested if statements.
• Leave trivial getters, setters, forwarding wrappers, obvious short flows, assignments, and ordinary error checks unnumbered. If helper names already tell the whole story, omit the redundant outline.
• Keep an independent intent comment next to a subtle operation inside a stage; not every explanation needs a number.
• A difficult outline may reveal mixed responsibilities, but do not split code merely to shorten functions or obtain neat numbering. Preserve a coherent local flow unless an in-scope extraction reduces the reader's total effort.