adriano-voice-code-comments

Adriano's Code-Comment Voice

Apply this whenever you write or edit a comment in source code. It governs how a comment reads, and helps decide whether a line deserves a comment at all. It is not a prose-rewriting tool — for Slack, PR descriptions, or review feedback, use [[adriano-voice]].

This guide was distilled from 800+ comment lines Adriano (acaloiaro) authored across his work repositories, tagged by altitude (class/module, method, inline). To re-derive it, see Refreshing this guide.

The one rule that matters most

A comment earns its place by explaining what the code cannot say itself — almost always the why, the contract, or the gotcha. Adriano does not narrate mechanics that the code already states. He comments:

• the reason a non-obvious line exists ("…because AMS wants ApplicationsSerializer to be an array serializer"),
• the contract of a method (what it returns, what it assumes, what it mutates),
• the caveat — a misnomer, a temporary hack, a backward-compat constraint, a performance footgun.

If a comment would only restate the code, drop it.

Only assert a why you have verified in the source. A confidently wrong rationale is worse than no comment — it outlives the code and misleads every reader after you. When you haven't confirmed the mechanism (especially one that lives in another service or repo), say less, or pitch the why at the altitude you can actually vouch for. "The worker never reads linked_data_id" is something this file proves; "linked_data_id is the Kafka partition key" is a claim about a producer you'd have to go read first.

Shared core (inherited from adriano-voice)

These carry over verbatim from [[adriano-voice]] — apply them in comments too:

• Rationale is never optional. The "because / so that / to ensure" clause is the spine of the comment.
• Concrete over abstract — but only for symbols a reader of this file can resolve. Name the real method, type, setting, flag, ticket. Never "the helper" when you can write param_to_person_attachment_id. The exception is code that lives in another codebase: name the system, not its internal class — write "link's producer", not GlobalSyncEventProducer (that symbol is invisible and unstable from where the comment sits). Reach for a foreign class name only when you genuinely must.
• State the subject; full sentences. Comments are sentences with subjects and verbs, not headline fragments. "This method name is a misnomer." — not "misnomer here."
• Low ceremony, short. No filler, no apology, no restating the obvious. Say the point once.
• Honest about debt. Name misnomers, hacks, and temporary code plainly. Don't dress them up.

By altitude

The voice shifts with what the comment documents. Match the altitude.

Class / module level — what this thing is and what it owns

Open by naming the thing and its responsibility, in present tense, full sentence. Then document defaults, config knobs, and the gotchas a caller needs before they reach for it.

# AuthenticationTokenService provides expiring authentication token functionality for API clients. Tokens
# generated by this service should be refreshed periodically by clients, as they may expire.
#
# Token expiry is _off_ by default. However, expiration may be enabled in two ways: 1. By setting
# +Settings.mobile_auth_token_service.token_lifetime+ (either with the environment variable, or in YAML), or
# 2. by enabling an organization's +mobile_use_org_session_timeout+ feature flag.

# This service module separates permission concerns from the +User+ model.

• Document defaults and config by exact name (+Settings.…+, the flag, the env var), not "configurable."
• Cross-reference collaborators: "Model merges occur in People::MergeService when Person and Application records are merged."
• For workers/jobs/tasks, embed a usage example in the doc block so callers can copy it:

  # Toggle the status of a single product flag across multiple orgs.
  #
  # BulkProductFlagWorker.toggle_async([1,2,3,4], :product_flag_name, false, run_at: Time.zone.now + 1.day)
  

Method level — the contract and the why

Lead with a third-person verb describing what the method does ("Returns…", "Renders…", "Authorizes…", "Generates…"), or an imperative for commands ("Create a new event"). Then state the contract precisely — what comes back, in what shape, under what conditions.

A single line is fine when one line says it all — don't inflate it into a block. Split into a summary line and details only when there's more to say. When you do split, structure it as: one summary line, a blank comment line, then the details. The first line stands alone as the synopsis (params, edge cases, and contract go below the break) — never run the summary straight into the explanation.

# Claim Checks the event's payload via `GET /v1/sync_events/:id`.
#
# The first call against an `announced` event transitions it `announced -> processing` in Link. Returns
# `[bytes, headers]`, or the `:already_synced` sentinel when there is nothing left to process.

When the surrounding error class and a log line already make a rescue/branch self-evident, don't restate it inline — lift the contract that is worth keeping up to the method's doc comment instead of narrating each branch.

# Returns a hash where keys are HiringPlanInterviewStage IDs and values are the number of applications pending
# review for the corresponding HPIS in +hiring_plan+.

# CRC32 fingerprints are _not_ to be used for cryptographic purposes or ensuring global uniqueness.
# Uses of CRC32 fingerprints should be localized and used only for performance reasons.

• Use RDoc params when the file already does: # @param [User] user The user being authorized / # @return an EventProspectRequest representing the answers.
• Reference params and identifiers inline. In legacy Ruby that's RDoc +user+; in modern code use backticks (`user`) unless the surrounding file already uses +…+. The principle — always mark identifiers — matters more than the delimiter.
• Use _emphasis_ (RDoc italics) for the stressed word: "asked at all events", "off by default".
• Link external docs with a bare # See https://example.com/api/#approve.

Inline / statement level — why this line, right here

This is where the voice is sharpest. Explain the surprising line, almost always with a causal clause.

# Cannot use `render :json => apps, ...` here because AMS wants `ApplicationsSerializer` to be an array serializer.

# redis stores all values as strings; convert row ids back to integers

# This only adds the role to the user temporarily because the `user` is not `saved`.

• Guards/preconditions read as imperatives: "Ensure organization has Prospects access", "Ensure user has correct permissions".
• Flag misnomers and debt candidly: "This method name is a misnomer. There is nothing mobile-specific about this URL."
• Test mechanics explain the stub's purpose: "stubbing out transaction allows permissions to be tested without testing the entirety of ApplicationService.move."

Language conventions

• Go: follow godoc — the comment opens with the identifier name. "ErrorRecovery is a Negroni middleware that recovers from any panics…", "NewRecovery returns a new instance of ErrorRecovery."
• Ruby: RDoc-flavored as above; # comments, +ident+ in legacy files, backticks in new ones.
• Always match the surrounding file's existing comment convention over this guide when they conflict.

TODO discipline

A TODO without a condition is noise. Adriano's TODOs carry either a ticket or a concrete unblocking condition — ideally both:

# TODO: change to job_post.touch after <tracker>/browse/TICKET-17245 bakes in
# TODO: When all environments are running new code, remove the second parameter and rename `param` `request_json`
# TODO: Refactor so as not to use Float::Infinity. The semantics are not clear to new developers.

Write # TODO: <action> <when/why it's unblocked>. If there's a ticket, cite it.

Mechanics checklist

• Identifiers in backticks (or +…+ in legacy RDoc files). Never bare.
• _word_ for emphasis on the one word that carries the caveat.
• Numbered enumerations for multi-case logic: "two conditions under which a worker should be drained, 1. … or 2. …".
• Examples embedded in doc blocks — call examples for workers, "Example response: …" for endpoints.
• # See <url> for external references; cite the tracker ticket for behavior tied to one.

Strip list (these are not in Adriano's voice)

• Restating the code: # increment the counter above counter += 1. Delete it.
• Flattery / hedging / AI throat-clearing: "Note that", "It's worth mentioning", "Simply", "Just".
• Inflated adjectives: "robust", "seamless", "powerful", "leverage". Say what it does.
• Bare TODOs with no ticket and no condition.
• Headline fragments with no subject ("misnomer here", "perf hack"). Write the sentence.
• Decorative banners and section separators unless the file already uses them.

Refreshing this guide

The patterns above are distilled, not live. To re-derive from current code (uses jj, per Adriano's no-git rule; assumes the repos are jj-colocated):

cd <a repo where you've authored substantial code>   # repeat for each
# Adriano's identities, excluding coworker "juan" and pairing (+juan) emails:
REV='author_date(before:"2025-01-01") & (author(substring:"caloiaro") | author(substring:"adriano.fyi")) ~ author(substring:"+juan")'
# Dump his diffs, then pull added comment lines and the code each one anchors to.
for id in $(jj log --no-graph -r "$REV" -T 'commit_id ++ "\n"'); do jj diff --git -r "$id"; done > /tmp/diffs.txt

Then classify each added comment by the next code construct it precedes (class/module → class-level, def → method-level, otherwise → inline) and re-distill the altitude sections. Drop the pre-2025 date bound to include recent work. Note: author() defaults to exact match in jj — use substring: for partial matches.