mirror of
https://git.numenor-labs.us/dsfx.git
synced 2025-04-29 16:20:34 +00:00
157 lines
6.3 KiB
Markdown
157 lines
6.3 KiB
Markdown
# TigerStyle for Go – Inspired by the Original TigerStyle
|
||
|
||
_This guide draws direct inspiration from the original TigerStyle document. Its principles have been adapted to the Go ecosystem, establishing definitive rules for writing safe, high-performance code with an exceptional developer experience._
|
||
|
||
---
|
||
|
||
## 1. The Core Principles
|
||
|
||
Our goal is to write Go code that is:
|
||
|
||
- **Safe:** No surprises. Every error is caught and handled.
|
||
- **High-Performance:** Bottlenecks are identified and efficiently addressed.
|
||
- **Easy to Maintain:** Code is clear, well-organized, and thoroughly documented.
|
||
|
||
---
|
||
|
||
## 2. Why Strict Style Matters
|
||
|
||
Adhering to strict rules ensures:
|
||
|
||
- **Clarity and Consistency:** Every developer on the team can immediately understand the code.
|
||
- **Early Error Detection:** Explicit checks and assertions catch mistakes before they become costly.
|
||
- **Reduced Technical Debt:** Investing time in clear design saves time later in production fixes and maintenance.
|
||
|
||
---
|
||
|
||
## 3. Simplicity and Elegance
|
||
|
||
- **Simple Designs First:** Strive for solutions that solve multiple issues simultaneously.
|
||
- **Iterate to Elegance:** The first solution is rarely the best. Refactor until your code is as simple as possible without sacrificing clarity.
|
||
- **Definitive Boundaries:** If something is too complex or too long, it must be split into distinct, manageable components.
|
||
|
||
---
|
||
|
||
## 4. Zero Technical Debt Policy
|
||
|
||
- **Fail Early:** Address potential issues during development—not after deployment.
|
||
- **No Compromise on Quality:** Code must fully meet our design standards before it can be merged.
|
||
- **Comprehensive Testing:** All functions must be covered by tests that include both valid and invalid cases.
|
||
|
||
---
|
||
|
||
## 5. Safety: Rules and Assertions
|
||
|
||
Safety comes first. Our practices include:
|
||
|
||
- **Control Flow and Limits:**
|
||
|
||
- Use clear, linear control structures. No clever hacks that compromise readability.
|
||
- Every loop, channel, and buffer **must have an explicit, hard upper limit**. For example, a loop should never exceed a fixed iteration count unless justified.
|
||
|
||
- **Assertions and Error Handling:**
|
||
|
||
- Every function **must validate its inputs and expected outputs**.
|
||
- Use explicit error checks (`if err != nil { … }`) to handle all non-fatal errors.
|
||
- For invariants that must never be violated, use `panic` immediately. Such panics are reserved solely for truly unrecoverable conditions.
|
||
- **Minimum Assertion Density:** Every function must include at least **two assertions or validations**—one confirming expected conditions and one ensuring the rejection of impossible states.
|
||
|
||
- **Resource Management:**
|
||
|
||
- Preallocate slices and buffers in hot paths to avoid runtime allocation surprises.
|
||
- All resources should be allocated once during startup, particularly in performance-sensitive parts of the system.
|
||
|
||
- **Variable Scoping:**
|
||
|
||
- Declare variables in the smallest scope possible. Global variables and unnecessarily wide variable scopes are not allowed.
|
||
|
||
- **Function Size:**
|
||
- **Hard limit:** No function may exceed **70 lines of code**. Functions that approach this limit must be refactored immediately into smaller helper functions with well-defined responsibilities.
|
||
|
||
---
|
||
|
||
## 6. Performance: Measured and Proven
|
||
|
||
- **Identify Bottlenecks:** Optimize in order: Network > Disk > Memory > CPU.
|
||
- **Profiling is Mandatory:** Use tools like `pprof` to physically measure performance. No assumptions—optimize based on real data.
|
||
- **Batch Operations:** Always batch I/O and computational tasks where possible to reduce overhead.
|
||
- **Explicit Critical Paths:** Code that is performance-critical must be isolated, clearly documented, and benchmarked. No “magic” will hide inefficient loops or algorithms.
|
||
|
||
---
|
||
|
||
## 7. Developer Experience: Consistency and Clarity
|
||
|
||
### Naming and Organization
|
||
|
||
- **Naming Conventions:**
|
||
|
||
- Use **CamelCase** for exported identifiers and **lowerCamelCase** for unexported ones.
|
||
- Names must be descriptive and avoid abbreviations unless the abbreviation is well recognized.
|
||
|
||
- **File and Code Organization:**
|
||
|
||
- The `main` function and package initialization must appear at the top of the file.
|
||
- Group related types and functions together. Consistent ordering enhances readability.
|
||
|
||
- **Commit Messages and Documentation:**
|
||
- Every commit must include a clear explanation of what changed and, more importantly, why the change was made.
|
||
- Comments must clarify the rationale behind decisions and describe non-obvious logic.
|
||
|
||
### Error Handling and Modularity
|
||
|
||
- **Explicit Error Checks:**
|
||
|
||
- Use the standard Go idiom (`if err != nil { … }`) without exception.
|
||
- Never ignore errors.
|
||
|
||
- **Function Design:**
|
||
|
||
- Functions must be single-purpose and maintain a clear separation of concerns.
|
||
- Avoid overly complicated signatures—simplicity at the point of use is paramount.
|
||
|
||
- **Testing:**
|
||
- Unit tests are mandatory for every function, covering both expected and edge-case scenarios.
|
||
- Tests must also deliberately check for error conditions and validate that assertions are working.
|
||
|
||
---
|
||
|
||
## 8. Tools, Dependencies, and Workflow
|
||
|
||
### Dependencies
|
||
|
||
- **Minimal External Dependencies:**
|
||
- Rely heavily on Go’s standard library. External libraries are permitted only when absolutely necessary and must be scrutinized for maintenance, security, and performance impact.
|
||
|
||
### Tooling
|
||
|
||
- **Formatting:**
|
||
|
||
- Code must be formatted with `gofmt`. No exceptions.
|
||
|
||
- **Static Analysis:**
|
||
|
||
- Run `go vet`, and other static analyzers with every commit. Fix all warnings immediately.
|
||
|
||
- **Version Control and CI/CD:**
|
||
- Use Go modules for dependency management.
|
||
- Integrate linting and testing into the CI pipeline to maintain consistency and catch issues early.
|
||
|
||
---
|
||
|
||
## 9. Final Mandates
|
||
|
||
- **Continuous Improvement:**
|
||
|
||
- This document is the definitive style guide for our Go code. Adherence is not optional.
|
||
- Regular audits, code reviews, and performance benchmarks must be conducted to ensure compliance.
|
||
|
||
- **No Excuses:**
|
||
- If a piece of code violates these rules, it must be refactored immediately.
|
||
- Our style ensures that every line of code is safe, efficient, and maintainable.
|
||
|
||
---
|
||
|
||
_End of TigerStyle for Go_
|
||
|
||
_We take inspiration from TigerStyle without compromise. Our rules are definitive and non-negotiable—engineered to produce Go code that stands out for its clarity, safety, and performance._
|