public/crypto-price-bot
6
0
Fork 0
Code Issues 1 Pull Requests 2 Actions Packages Projects Releases Wiki Activity

docs: broaden spec to repo-wide go filename consistency

Browse Source 
Update issue #26 design scope from market-only to repository-wide .go filename refactor while keeping behavior unchanged.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
thuanle
2026-04-27 05:14:49 +07:00
parent 8010a00e4d
commit bc99d40713
1 changed files with 44 additions and 44 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/superpowers/specs/2026-04-27-market-filenames-data-dimension-design.md
+44 -44
View File
@@ -1,62 +1,60 @@
# Market filenames data-dimension design # Go filenames consistency design
## Context ## Context
`internal/data/market` currently has mixed filename semantics (`trading_pairs.go`, `future_price.go`, `spot_price.go`, `alpha_tokens.go`). The repository has inconsistent `.go` filename semantics in multiple areas (domain-oriented names, endpoint/history-oriented names, mixed singular/plural forms).
This slows code navigation because filenames do not consistently communicate data dimension. This slows code navigation because filenames do not consistently communicate data dimension or responsibility.
Goal: refactor market package filenames to consistent data-dimension naming, and align function placement with filename responsibility, without changing runtime behavior. Goal: refactor `.go` filenames across the whole repository to a consistent naming model, and align declaration placement with filename responsibility, without changing runtime behavior.
## Scope ## Scope
Applies only to files in `internal/data/market`. Applies to all `.go` files in the repository.
In scope: In scope:
- Rename files to consistent names by data dimension. - Rename `.go` files to consistent, responsibility-first names.
- Mechanical updates needed due to file rename/move. - Mechanical updates required by rename/move.
- Move functions between renamed files when needed so file responsibility is clear. - Move declarations between files when needed so file responsibility is clear.
Out of scope: Out of scope:
- Any behavior or logic changes. - Any behavior or logic changes.
- Non-`.go` files.
- New feature work. - New feature work.
- Refactors outside `internal/data/market` except mechanical references.
## Requirements ## Requirements
1. File naming in market package is consistent by data dimension. 1. `.go` filename naming is consistent across the repository.
2. Target filenames: 2. Filenames follow responsibility-first conventions:
- `spot_pairs.go` - data-dimension names where applicable (`spot_*`, `futures_*`, etc.)
- `futures_pairs.go` - pluralized collection-oriented files (`*_pairs.go`, `*_prices.go`)
- `spot_prices.go` - avoid endpoint/history-oriented naming that obscures responsibility.
- `futures_prices.go` 3. Declarations in each file match filename responsibility.
- keep `alpha_tokens.go`
3. Function placement matches filename responsibility.
4. No public/package behavior change. 4. No public/package behavior change.
5. Resulting PR focuses on refactor readability and low review noise. 5. Resulting PR remains reviewable by grouping changes mechanically and keeping logic untouched.
## Design ## Design
### Naming model ### Naming model
Use pluralized, data-dimension based filenames: Use a responsibility-first naming model for all `.go` files:
- `*_pairs.go` for symbol/pair resolution concerns. - A reader should infer the primary responsibility from filename alone.
- `*_prices.go` for price retrieval/processing concerns. - Prefer domain/data-dimension names over transport/implementation-history names.
- Use consistent singular/plural convention based on file content (entity vs collection).
### File-level responsibilities
- `spot_pairs.go`: Spot pair/symbol resolution code.
- `futures_pairs.go`: Futures pair/symbol resolution code.
- `spot_prices.go`: Spot price read/transform code.
- `futures_prices.go`: Futures price read/transform code.
- `alpha_tokens.go`: Alpha-token specific logic (unchanged file name).
### Refactor mechanics ### Refactor mechanics
1. Rename existing files to target names using git-aware rename. 1. Inventory `.go` files by package and classify naming inconsistencies.
2. Inspect each renamed file for responsibility mismatch. 2. Define target filename map package-by-package.
3. Move declarations to the matching file when mismatch exists. 3. Rename files with git-aware rename operations.
4. Keep function signatures and call behavior unchanged. 4. Move declarations when file content does not match filename responsibility.
5. Apply only mechanical import/reference updates if any are required. 5. Keep signatures and bodies unchanged.
6. Apply only mechanical reference/import updates required by moves.
### Execution strategy for reviewability
- Use focused commits by package or subsystem.
- Keep each commit behavior-neutral.
- Separate any necessary declaration moves from broad rename waves when this improves diff readability.
## Error handling and behavior ## Error handling and behavior
@@ -65,21 +63,23 @@ Existing control flow and error behavior remain unchanged.
## Testing and verification ## Testing and verification
1. Run package tests for market-related code. 1. Run project tests after each major package/subsystem batch.
2. Run project test command used by repository. 2. Run full project test command before PR.
3. Confirm no functional diff beyond file rename/moves. 3. Confirm no functional diff beyond rename/move/mechanical updates.
4. Final check: each renamed file contains only code matching its data dimension. 4. Final check: each renamed file contains declarations aligned with its responsibility.
## Risks and mitigations ## Risks and mitigations
- Risk: accidental behavior change while moving declarations. - Risk: accidental behavior change while moving declarations.
- Mitigation: keep signatures/body unchanged; validate with tests. - Mitigation: keep signatures/bodies unchanged and validate with tests per batch.
- Risk: review noise from mixed mechanical and logic edits. - Risk: review noise from repo-wide scope.
- Mitigation: avoid logic edits entirely; keep commit focused on naming/responsibility alignment. - Mitigation: package-grouped commits, strict mechanical-only edits, and explicit PR summary.
- Risk: large PR becomes hard to review.
- Mitigation: preserve commit structure and provide a clear rename map in PR description.
## Success criteria ## Success criteria
- Market package filenames follow the target naming scheme. - `.go` filenames are consistent and responsibility-first across the repo.
- Code in each file matches its filename responsibility. - Declarations in each file align with filename responsibility.
- Tests pass with no behavior regression. - Tests pass with no behavior regression.
- PR is reviewable as a refactor-only change set. - PR is understandable through structured, behavior-neutral commits.