Skip to content

chore: trim the Midnight comments down to what is worth reading - #54

Merged
ctoyan merged 1 commit into
midnight-v1from
chore/humanize-midnight-comments
Aug 25, 2026
Merged

chore: trim the Midnight comments down to what is worth reading#54
ctoyan merged 1 commit into
midnight-v1from
chore/humanize-midnight-comments

Conversation

@ctoyan

@ctoyan ctoyan commented Aug 25, 2026

Copy link
Copy Markdown

Comment-only pass over the Midnight work, in two rounds: the first rewrote the
overlong comments, the second deleted the ones that should not have existed at
all. Net ~900 lines of comment removed.

What went

  • Docs that only echoed the item name. toolkit.rs alone had about a
    hundred: the same /// Operation discriminator / /// Indexer GraphQL endpoint (HTTP) block repeated across six near-identical request structs.
    Nothing in that module is reachable outside the crate, so none of it was
    required by missing_docs — confirmed by clippy after removal.
  • Module and crate headers written as essays. The Rust siblings
    (hyperlane-cosmos, hyperlane-aleo, hyperlane-sealevel) all open with a
    single line, so these do too, keeping only what is not visible from the code:
    the feature gate, the off-chain merkle tree, the Bytes<N> trailing-zero
    trim. merkle_tree_hook.rs went 36 header lines to 10, metadata_tests.rs
    31 to 12, state_decode.rs 22 to 7.
  • Comments restating the assertion beneath them. A line reading "a shared
    prefix does not match" sitting above an assert that a shared prefix does not
    match tells nobody anything.
  • Cross-chain trivia. Whether a choice matches EVM, Aleo, or Sealevel is
    interesting while writing the code and useless while reading it. It stays
    only where it grounds a whole design (the off-chain merkle tree).
  • Every #N issue reference, including two in runtime strings: a todo!()
    message and an error message a user could actually see.
  • Match-arm narration. The Midnight arms in chains.rs, cursors/mod.rs
    and chain.rs each had a comment describing the line below it, where every
    surrounding arm has none. One was also stale — it still described reading
    count/current_root from an on-chain merkle tree that was removed. The
    state_decode.rs header was stale too: it listed field positions ([0, 8],
    [0, 9]) that contradicted the actual constants directly below it.
  • Version detail that dates fast (compact-js, wallet-sdk, midnight-js, node)
    where the behaviour is the point. The reason the chunked deploy is hand-built
    at the ledger level is still there; the exact version that forced it is not.
  • Stale claims. The midnight-sdk README no longer says "under
    construction", and the PARTIAL_SUCCESS note no longer says segment
    attribution is still being verified — that was confirmed safe.
  • core-config.yaml trimmed from a 14-line preamble to 5, matching the
    other example configs.

Three changes that are not comments

Flagging these since everything else is comment-only:

  1. Deleted announce_and_read_back_on_devnet in validator_announce.rs. It was
    #[ignore] plus unimplemented!() and a four-step plan in a comment — it
    never ran and never asserted anything. Say the word if you'd rather keep the
    placeholder.
  2. Renamed tx_status_filter_is_the_single_decision_point to
    tx_status_filter_excludes_only_failures, so the name says what it asserts.
  3. Dropped an unnecessary mut in mailbox.rs.

Verification

  • cargo test -p hyperlane-midnight — 84 passed, 3 ignored
  • cargo clippy -p hyperlane-midnight --all-targets — no missing_docs, no new
    warnings (one pre-existing is_multiple_of suggestion, untouched by this PR)
  • cargo check -p hyperlane-base -p relayer -p lander -p validator --features midnight — clean
  • cargo fmt --all --check — clean
  • tsc --noEmit on sdk and cli; builds green for midnight-sdk, provider-sdk,
    deploy-sdk
  • oxlint clean on every touched TS file
  • Diffed every changed file with comment lines stripped, against both the base
    and the first round: the only non-comment changes are the three above.

Most of the Midnight comments were doing too much: module headers that ran
20-30 lines, doc comments restating the signature below them, and match arms
narrated line by line where every sibling arm is bare. Cut them back to the
non-obvious facts and deleted the rest outright.

What went:
- Doc comments that only echoed the item name. `toolkit.rs` alone had about a
  hundred of these, the same "Operation discriminator" / "Indexer GraphQL
  endpoint" block repeated across six near-identical request structs. Nothing
  in that module is reachable outside the crate, so none of it was required.
- Design essays in the crate and module headers. The Rust siblings open with
  one line, so these do too, keeping only what is not visible from the code:
  the feature gate, the off-chain merkle tree, the trailing-zero trim.
- Comments restating the assertion underneath them. A line reading "a shared
  prefix does not match" above an assert that a shared prefix does not match
  is not telling anyone anything.
- Cross-chain trivia. Whether a choice matches EVM, Aleo, or Sealevel is
  interesting while writing the code and useless while reading it, so it stays
  only where it grounds a whole design.
- Every #N issue reference in code and docs.
- Narration of the Midnight arms in chains.rs, cursors/mod.rs, and chain.rs.
  One was also stale, still describing an on-chain merkle tree that was
  removed.
- Tool and version detail that dates fast (compact-js, wallet-sdk, node and
  midnight-js versions) where the behaviour is the point, not the version.
- The devnet integration test that was only an unimplemented!() and a
  four-step plan in a comment.
- The stale "under construction" note in the midnight-sdk README and the
  "verified separately" note on PARTIAL_SUCCESS, which has since been
  confirmed safe.

Also renamed one test to say what it asserts and dropped an unused mut.
No behaviour change: cargo test -p hyperlane-midnight is 84 green, clippy
reports no missing docs, tsc and oxlint clean across the touched packages.
@ctoyan
ctoyan force-pushed the chore/humanize-midnight-comments branch from 75a5f81 to 6b38022 Compare August 25, 2026 20:41
@ctoyan ctoyan self-assigned this Aug 25, 2026
@ctoyan
ctoyan merged commit 65d8f61 into midnight-v1 Aug 25, 2026
29 of 91 checks passed
@ctoyan
ctoyan deleted the chore/humanize-midnight-comments branch August 25, 2026 20:55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant