Coding Practices
1. Clean Code & Structural Readability
Prioritize Intention-Revealing Names
Code must document itself through semantic naming. Avoid generic shorthand or single-letter variables unless they are standard mathematical invariants (like i in a brief loop).
Weak: const d = getVal(u);
Strong: const daysSinceLastLogin = calculateDaysSinceLogin(userAccount);
Rule: If a variable name requires an accompanying comment to explain what it represents, the variable name has failed.
Exploit Guard Clauses to Flatten Nesting
Deeply nested if/else statements drastically increase cyclomatic complexity (the number of linear execution paths through code). Instead, check for invalid states or edge cases early, return or throw immediately, and keep the "happy path" aligned to the left edge of the screen.
TypeScript
// Avoid: Deep Arrow Anti-Pattern
function processPayment(user, order) {
if (user.isActive) {
if (order.hasItems) {
if (paymentGateway.isUp()) {
// Core logic buried 4 levels deep
}
}
}
}
// Prefer: Guard Clauses
function processPayment(user, order) {
if (!user.isActive) return logAndAbort("User inactive");
if (!order.hasItems) return logAndAbort("Empty order");
if (!paymentGateway.isUp()) throw new GatewayException();
// Happy path runs clearly at the root level
}
2. Architectural Paradigms & Abstractions
Avoid Hasty Abstractions (AHA Programming)
While duplication is an anti-pattern, over-engineering is worse. Duplication is far cheaper to refactor than a bad, highly coupled abstraction. Do not extract logic into a shared helper or global component until you have seen the exact pattern repeated at least three times across distinct, unrelated domains.
Enforce Separation of Concerns (SoC)
A single function or file should solve exactly one problem.
UI Components: Responsible solely for layout and binding event handlers. They should not calculate tax rates or execute complex raw SQL operations.
Business Logic Controllers: Responsible for orchestration and data transformations.
Data Access Layer: Responsible strictly for communicating with databases or headless CMS instances.
3. Defensive Programming & State Integrity
Embrace Immutability Natively
Mutable state is the single largest source of unpredictable runtime bugs and side effects in complex web applications.
Treat data structures as read-only. When updating objects or arrays, return a fresh copy containing the modifications rather than changing the original instance in place.
Prefer pure functions (functions that always return the exact same output given the same input and cause zero side effects) for all utility and calculation logic.
Explicit and Structured Error Boundaries
Never write empty catch blocks (catch (e) {}) or generic logs that swallow failures silently.
Fail Fast: If a required system dependency, configuration key, or database connection is missing, crash the application process immediately at startup rather than allowing it to run in a corrupted, unpredictable state.
Contextual Errors: When throwing or bubbling up errors, append custom operational metadata (like user IDs or transaction types) so that external error tracking systems capture actionable debugging telemetry.
4. Type Safety & Contract Design
Avoid Speculative Logic
Write code for the software requirements that exist today, not for the hypothetical features you think might be requested six months from now. Speculative code introduces unneeded abstractions, bloats the surface area for bugs, and creates dead code paths that future engineers will be terrified to remove.
Enforce Strict Boundaries at Network Ingress
TypeScript guarantees type safety within your local application codebase, but it completely evaporates at the network boundary.
Never trust incoming third-party Webhook payloads or external REST API responses implicitly.
Run runtime schema validation (using tools like Zod) at your API ingress points. Validate that the external JSON data strictly matches your internal TypeScript contracts before letting that data touch your core business or database layers.