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
`internal/data/market` currently has mixed filename semantics (`trading_pairs.go`, `future_price.go`, `spot_price.go`, `alpha_tokens.go`).
This slows code navigation because filenames do not consistently communicate data dimension.
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 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
Applies only to files in `internal/data/market`.
Applies to all `.go` files in the repository.
In scope:
- Rename files to consistent names by data dimension.
- Mechanical updates needed due to file rename/move.
- Move functions between renamed files when needed so file responsibility is clear.
- Rename `.go` files to consistent, responsibility-first names.
- Mechanical updates required by rename/move.
- Move declarations between files when needed so file responsibility is clear.
Out of scope:
- Any behavior or logic changes.
- Non-`.go` files.
- New feature work.
- Refactors outside `internal/data/market` except mechanical references.
## Requirements
1. File naming in market package is consistent by data dimension.
2. Target filenames:
- `spot_pairs.go`
- `futures_pairs.go`
- `spot_prices.go`
- `futures_prices.go`
- keep `alpha_tokens.go`
3. Function placement matches filename responsibility.
1. `.go` filename naming is consistent across the repository.
2. Filenames follow responsibility-first conventions:
- data-dimension names where applicable (`spot_*`, `futures_*`, etc.)
- pluralized collection-oriented files (`*_pairs.go`, `*_prices.go`)
- avoid endpoint/history-oriented naming that obscures responsibility.
3. Declarations in each file match filename responsibility.
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
### Naming model
Use pluralized, data-dimension based filenames:
- `*_pairs.go` for symbol/pair resolution concerns.
- `*_prices.go` for price retrieval/processing concerns.
### 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).
Use a responsibility-first naming model for all `.go` files:
- A reader should infer the primary responsibility from filename alone.
- Prefer domain/data-dimension names over transport/implementation-history names.
- Use consistent singular/plural convention based on file content (entity vs collection).
### Refactor mechanics
1. Rename existing files to target names using git-aware rename.
2. Inspect each renamed file for responsibility mismatch.
3. Move declarations to the matching file when mismatch exists.
4. Keep function signatures and call behavior unchanged.
5. Apply only mechanical import/reference updates if any are required.
1. Inventory `.go` files by package and classify naming inconsistencies.
2. Define target filename map package-by-package.
3. Rename files with git-aware rename operations.
4. Move declarations when file content does not match filename responsibility.
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
@@ -65,21 +63,23 @@ Existing control flow and error behavior remain unchanged.
## Testing and verification
1. Run package tests for market-related code.
2. Run project test command used by repository.
3. Confirm no functional diff beyond file rename/moves.
4. Final check: each renamed file contains only code matching its data dimension.
1. Run project tests after each major package/subsystem batch.
2. Run full project test command before PR.
3. Confirm no functional diff beyond rename/move/mechanical updates.
4. Final check: each renamed file contains declarations aligned with its responsibility.
## Risks and mitigations
- Risk: accidental behavior change while moving declarations.
- Mitigation: keep signatures/body unchanged; validate with tests.
- Risk: review noise from mixed mechanical and logic edits.
- Mitigation: avoid logic edits entirely; keep commit focused on naming/responsibility alignment.
- Mitigation: keep signatures/bodies unchanged and validate with tests per batch.
- Risk: review noise from repo-wide scope.
- 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
- Market package filenames follow the target naming scheme.
- Code in each file matches its filename responsibility.
- `.go` filenames are consistent and responsibility-first across the repo.
- Declarations in each file align with filename responsibility.
- Tests pass with no behavior regression.
- PR is reviewable as a refactor-only change set.
- PR is understandable through structured, behavior-neutral commits.