Engineering Philosophy & Code of Conduct

Every codebase reflects the culture of the team that built it. This document defines the foundational principles that guide how we collaborate, write code, and make architectural decisions. It is not a style guide — it is a statement of intent.

The goal is simple: build software that is easy to reason about, easy to change, and a pleasure to work in — not just for the person who wrote it, but for everyone who comes after.

Collaboration & Respectful Communication

Shared Ownership

There is no such thing as “your code” or “my code” — there is only our codebase. Every engineer is encouraged to propose improvements to any part of the system, and equally expected to welcome feedback on their own contributions without defensiveness.

This shared ownership model eliminates knowledge silos. When the whole team understands the whole system, bus factor drops to zero and velocity compounds over time.

Constructive Code Reviews

A code review is not a performance review. Its sole purpose is to make the code better.

• Reviewers: Be specific and kind. Focus on the code, not the author. When something is unclear, ask a question rather than make an assumption.
• Authors: Default to assuming good intent. A comment pointing out a flaw is a gift, not an attack.

💡 The golden rule: Would you be comfortable if your feedback appeared on a public technical blog, attributed to you by name? Write accordingly.

Open Technical Discussion

Architecture decisions and complex problem-solving should happen in the open — in pull request threads, design documents, or team discussions — not in private Slack DMs or unwritten assumptions.

If you disagree with a decision, the right move is to articulate your reasoning in a shared space, not to silently implement an alternative.

Coding Principles & Consistency

Follow Established Conventions

This blueprint documents our conventions in detail: naming, file structure, API design, error handling, and more. These are not arbitrary rules — they are decisions that have already been made so that you don’t have to remake them on every feature.

Following conventions consistently means that any engineer can open any file in the codebase and immediately understand its purpose and structure. That predictability is immensely valuable at scale.

Write for the Reader, Not the Compiler

“Code is read far more often than it is written.” — Robert C. Martin

Prioritize clarity over cleverness. Choose descriptive variable names over short ones. Keep functions small and focused on a single responsibility. Avoid deep nesting. If a function needs a lengthy comment to explain what it does, it probably needs to be refactored.

Comment the Why, Not the What

The code itself should explain what it does. Comments are for explaining why — the reasoning behind a non-obvious decision, a business rule that doesn’t map cleanly to code, or a known limitation you’re working around.

// ❌ Useless comment — the code already says this
const user = await userRepository.findOne(id); // Find one user by ID

// ✅ Useful comment — explains context that code cannot
// We intentionally skip cache here. This endpoint is only called during
// audit logging, where stale data could produce an incorrect audit trail.
const user = await userRepository.findOne(id);

Architectural Alignment

Understand the Why Behind Every Decision

This blueprint makes opinionated choices: Nx monorepo, Clean Architecture, bounded contexts, stateful JWT. Each of these was selected for specific reasons. If you don’t understand why a pattern exists, ask before working around it.

Engineers who understand the why make better decisions in edge cases. Engineers who only know the what are forced to guess.

Design Before You Build

For any new feature of significant scope, invest time in design before writing code. This doesn’t need to be a formal document — a short ADR (Architecture Decision Record), a rough Mermaid diagram, or even a structured comment explaining the approach is enough.

The 30 minutes spent sketching a design can save days of refactoring a fundamentally flawed implementation.

Treat Documentation as Code

Documentation that describes a system that no longer exists is worse than no documentation — it actively misleads. When you change how something works, update the corresponding guide.

📌 Rule of thumb: If you write a PR that changes a documented behavior, that PR is not complete until the docs are updated too.

---

These principles are not bureaucracy. They are the accumulated wisdom of engineering teams that have learned — often the hard way — what makes software sustainable at scale. Follow them not because you are told to, but because you understand why they matter.