dsfx/tigerstyle.md

# 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._