thuanle
bc99d40713
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>
86 lines
3.4 KiB
Markdown
86 lines
3.4 KiB
Markdown
# Go filenames consistency design
|
|
|
|
## Context
|
|
|
|
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 `.go` filenames across the whole repository to a consistent naming model, and align declaration placement with filename responsibility, without changing runtime behavior.
|
|
|
|
## Scope
|
|
|
|
Applies to all `.go` files in the repository.
|
|
|
|
In scope:
|
|
- 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.
|
|
|
|
## Requirements
|
|
|
|
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 remains reviewable by grouping changes mechanically and keeping logic untouched.
|
|
|
|
## Design
|
|
|
|
### Naming model
|
|
|
|
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. 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
|
|
|
|
No new error handling paths are introduced.
|
|
Existing control flow and error behavior remain unchanged.
|
|
|
|
## Testing and verification
|
|
|
|
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/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
|
|
|
|
- `.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 understandable through structured, behavior-neutral commits.
|