2.6 KiB
2.6 KiB
Contract: Module Atomicity
Version: 1.1
Principle
Each file has one clear responsibility. A file that does many unrelated things is a liability, not a convenience.
Rules
- One concept per file. A file should be nameable in a single noun:
user_validator.go,session_store.go,invoice_pdf.go. If the name requires "and" or "misc", the file is too broad. - Do not append new functionality to an existing file because it is nearby or already open. When a new piece of logic does not belong to the existing concept, create a new file.
- A file that grows past ~200 lines is a signal to split, not a mandate — but treat it as a prompt to ask whether all the code in it shares a single responsibility.
- Package-level
utils.go,helpers.go, orcommon.gofiles are banned. Name the file after what the code actually does.
Anti-patterns
- Adding a new handler to
handlers.gobecause there is already a handler there. - Putting unrelated functions in the same file to avoid creating a new one.
- A single file containing models, queries, business logic, and HTTP concerns at once.
- Files named after their location or role in the codebase rather than their concept:
api.go,misc.go,util.go,shared.go.
When to split
Split a file when:
- You cannot describe all of its functions in one short sentence.
- A new function you are adding does not share the domain of the existing ones.
- The file has more than one reason to change independently.
Do not wait until a file is "too big." Split at the moment the second responsibility appears.
Repository Tooling
- Keep repository-owned helper programs and scripts under one root
tools/directory, regardless of language. Do not create parallelscripts/,script/ortool/directories for the same purpose. - Group a tool's supporting code, fixtures and usage notes with that tool; use named subdirectories when several files implement one tool.
- Fixed-location integration entry points, such as Git hooks and CI workflow
files, stay where their runner requires them. Reusable helper logic belongs
in
tools/. Application source and package-local test fixtures stay with their owning packages. - When moving an existing tool, update callers, CI, documentation and planned paths together. Preserve executable permissions and repository-root resolution.
- Generated reports and logs are output artifacts, not tools. Keep them untracked and document their output location. If the operator wants a report beside the standalone script, ignore that report in Git. Credentials and backup data must follow the applicable secrets and backup contracts.