Repository navigation
docs: tighten and cut comments in core packages - #697
Merged
Merged
Conversation
Shorten comments in internal/tui, chain, extension, state, storage, runtime, spine, bus, instance, orchestration and observe. Each remaining comment states an invariant, a failure it guards against, an ordering reason, a unit or range, or a wire contract; comments that restated the code or told its history are removed. Exported names keep a one-line doc. The change touches comments only: the non-comment token stream and the directive comments of every changed file are identical to main. Removes the baseline entries for the comment violations that no longer exist. Signed-off-by: Ion Alpha <contact@ionalpha.io>
Signed-off-by: Ion Alpha <contact@ionalpha.io>
Signed-off-by: Ion Alpha <contact@ionalpha.io>
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
Signed-off-by: Ion Alpha <contact@ionalpha.io>
Signed-off-by: Ion Alpha <contact@ionalpha.io>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Rewrites the comments in
internal/tui,chain,extension,state,storage,runtime,spine,bus,instance,orchestrationandobserve. Comments that restated the code or told its history are removed; the rest are shorter and keep only what the code cannot say: invariants, failure guards, ordering reasons, units and ranges, security and concurrency contracts, and wire-contract statements. Exported names keep a one-line doc, and every contract statement instateandextensionis kept. Production.gofiles only; no code changes.Why
The comment gate added in the last few PRs fixes the rules but leaves a large body of older comments that narrate the code. Shorter comments are easier to keep true, and the published API reference reads as a contract instead of a walkthrough. This also removes the baseline entries for violations that no longer exist.
How to verify
go test ./internal/rigor/...passes, includingTestCommentsStayTersewith the smaller baseline, and./dev/lintreports 0 issues. A scanner-level comparison of each changed file against its pre-change version (tokens with comments skipped, plus directive comments such as//go:embedand//nolint) shows all 105 files identical, so only comments differ.Notes for reviewers
Comment lines in these packages go from 5804 to 3326. The baseline loses 21 lines. Two entries stay because they are not fixed here:
chain/conformance/crypto.gostill has one over-long block.