Tech Guide

[RandintN]

💻 Tech Guide: Simplicity, Clarity, and Maintainability

"Standing on the shoulders of giants." – Our philosophy is to build upon established, clear, and proven foundations, prioritizing maintainability and directness over unnecessary complexity. Clarity is the ultimate measure of intelligence in code.

---

🚀 I. Core Principles

These principles guide all technical decisions and coding practices within the company.

1. Principle of Least Surprise (POLS)

• Goal: Write code that behaves exactly as the reader expects it to, minimizing cognitive load.
• Practice: Avoid "magic" behavior, side effects in functions, or overly clever logic. Explicit is always better than implicit.

2. YAGNI (You Aren't Gonna Need It)

• Goal: Focus on solving the current problem.
• Practice: Do not implement features, abstractions, or complex infrastructure for future needs that haven't materialized yet. Simple is faster to build and easier to change.

3. KISS (Keep It Simple, Stupid)

• Goal: Ensure the code is as straightforward and minimal as possible to achieve the required functionality.
• Practice: Choose the simplest data structure, algorithm, or pattern that solves the problem. Complexity is a liability, simplicity is an asset.

4. Directness and Humility in Design

• Goal: Designs should be easily understandable by anyone on the team, regardless of their experience level.
• Practice: If a solution requires a PhD-level explanation or an obscure design pattern, simplify it. We aim for results, not for proving intelligence through complication.

---

🛠️ II. Coding Practices

1. Naming

• Variables, Functions, Classes: Names must be full, unambiguous, and descriptive of what they are or what they do. Avoid abbreviations unless universally understood (e.g., HTTP).
• Boolean Variables: Should read as an assertion or question (e.g., isValid, isEnabled).

2. Functions and Methods

• Single Responsibility: Functions/methods should do one thing, and do it well (from the S.O.L.I.D. principles).
• Minimal Arguments: Aim for functions with zero to three arguments. If you need more, encapsulate related arguments into a well-named data object or class.
• Early Exit: Use guard clauses (fail fast) to handle error conditions and prerequisites early, reducing indentation and keeping the "happy path" clear.

3. Comments and Documentation

• Why, Not What: Good code explains what it does. Comments should explain why a particular design choice was made, why a known issue was worked around, or why a non-obvious requirement exists.
• Avoid Redundancy: Do not comment on what is already clear from the code or good naming.
• API/Public Interface Documentation: All public functions, methods, and classes must have clear, concise documentation explaining their purpose, parameters, and return value.

4. Error Handling

• Handle Errors Where They Occur: Errors should be handled as close as possible to the point of failure to provide context.
• Avoid Generic Catches: Do not catch the most generic exception type unless you are immediately re-throwing or logging the error and re-packaging it with context. Generic catch(Exception) is often a sign of laziness.
• Contextual Logging: Logs should be simple, clear, and include all necessary context (e.g., user ID, transaction ID, input parameters) to reproduce and debug the issue.

---

🏗️ III. Architectural Simplicity

1. KISS > DRY (Don't Repeat Yourself)

• The Premise: Premature abstraction is often the root of technical debt and complexity. Duplication is better than the wrong abstraction.
• Practice: Prioritize clarity (KISS) over avoiding repetition (DRY) in the early stages of a feature. It is acceptable to have some duplicated code if abstracting it would introduce ambiguity or unnecessary indirection. Wait for the duplication to occur three times or more before consolidating, as this ensures you understand the true common pattern, not just an assumed one.

2. Avoid Abstraction for Abstraction's Sake

• Rule: Only introduce an abstraction (e.g., an interface, a factory, a new layer) when you have two or more concrete implementations that genuinely benefit from it, or if it is required by a core team contract.

3. Dependency Management

• Minimize External Dependencies: Every third-party library is a liability (security, maintenance, vendor lock-in). Evaluate whether the benefit significantly outweighs the cost of maintaining the dependency.
• Inversion of Control (IoC) Containers: Use them to manage dependencies, but keep the configuration simple. Avoid overly complex constructor injection chains. The dependency graph should be shallow and clear.

4. Testing

• Directness in Tests: Tests should be simple, readable, and focused. The test name should clearly explain what is being tested.
• Maintainability Over Coverage: Aim for high coverage, but prioritize testing the critical paths and business logic with clear, direct tests that don't break with minor internal refactoring.