I used to think waiting on code reviews was just part of the job.

Finish a feature, open a PR, sit on it for a day or two. Context-switch to something unrelated, or branch off the unreviewed PR and start the next piece.

That second branch was technically a stack. Just an undisciplined one.

When PR 1 came back with feedback, my “head start” on PR 2 turned into a rebase nightmare.

The first time I worked with a properly stacked PR workflow, the difference was immediate.

I was still building on top of unreviewed work, but the rebases stopped hurting, the reviewers stopped drowning, and nothing got lost between layers.

Here’s what I wish someone had walked me through.

• Share this post & I’ll send you some rewards for the referrals.

The AI code reviewer that thinks like a senior engineer (Partner)

AI writes code faster than teams can review.

Codacy understands your codebase, catches real issues and intent gaps, and hands fixes to your agent.

Run it on your next PR →

(Thanks to Codacy for partnering on this post.)

What Stacked PRs Are (and Aren’t)

A stacked PR, also called a stacked diff, is a pull request whose base branch is another PR’s branch instead of main.

Instead of one big PR with 1,200 lines across 15 files, you break the work into a chain:

• PR 1 → base: main. Ships the data model change.

• PR 2 → base: PR 1’s branch. Ships the API layer.

• PR 3 → base: PR 2’s branch. Ships the UI.

Each PR is small, focused, and independently reviewable.

They merge bottom-up: PR 1 lands first, then PR 2, then PR 3. (More on the retargeting magic in a minute.)

This isn’t about creating more work. It’s about making the unit of review smaller and keeping yourself unblocked.

What it isn’t: a rule that says “one commit per PR”. It isn’t about turning your git history into art. It’s a practical workflow for shipping complex features without sitting on your hands.

Why Long-Lived Feature Branches Are the Real Problem

The traditional PR workflow looks like this:

1. Branch off main

2. Build the whole feature

3. Open one big PR

4. Wait

5. Address feedback (which has now diverged from what you remember)

6. Merge

The problems compound.

Big PRs get shallow reviews. Nobody reviews 1,200 lines of code carefully. They scan for obvious bugs, eyeball the logic, approve. The subtle stuff slips through.

You’re blocked while you wait. If the next piece depends on this one, you’re stuck. Or you do what I used to do — branch off the unreviewed PR with no plan for handling the rebases later.

Feedback loops are long. A comment lands on day 2. You’ve moved on mentally. Now you reload the context on the code you wrote 48 hours ago.

Merge conflicts compound. The longer a branch lives, the more it diverges from main. Every merge becomes a negotiation.

The idea is simple:

A feature isn’t the right unit of review. A focused change is.

A Concrete Example

You’re building user authentication: a new users table, a REST endpoint, and a login form.

Traditional approach:

• One branch: feature/auth

• One PR: ~1,200 lines, three subsystems, no clear entry point for a reviewer

Stacked approach (same total work, split into reviewable pieces):

• auth/01-users-table → base main (~200 lines, schema + migration)

• auth/02-auth-endpoint → base auth/01-users-table (~400 lines, POST /login)

• auth/03-login-form → base auth/02-auth-endpoint (~600 lines, React form + hook)

You open all three at once. Reviewers can start on PR 1 immediately. While they review, you keep working. When PR 1 gets feedback, you fix it on auth/01-users-table and rebase the rest of the stack on top.

The key shift: you don’t wait. You keep building on top of pending work, and reviews come in asynchronously.

Cascading Rebases: The Hard Part

Most posts about stacked PRs hand-wave this part. It’s actually where most of the pain lives.

This is what happens during review, before anything merges.

PR 1 gets feedback. You change history on auth/01-users-table — say, by amending the commit or rebasing, and every PR above it now points at a stale parent. You need to rebase the rest of the stack on top of the updated PR 1, in order.

If “rebase” is fuzzy: it means “take my commits, lift them off their old base, and stick them on top of a new one”. The commits get rewritten: same diff, new parent, new hash.

Manually, that’s:

# Update PR 1 (amend keeps the PR to one clean commit)
git checkout auth/01-users-table
# ...address feedback...
git commit --amend
git push --force-with-lease

# Rebase PR 2 onto the updated PR 1
git checkout auth/02-auth-endpoint
git rebase auth/01-users-table
git push --force-with-lease

# Rebase PR 3 onto the updated PR 2
git checkout auth/03-login-form
git rebase auth/02-auth-endpoint
git push --force-with-lease

Three things to remember:

1. --force-with-lease, not --force. It refuses to overwrite remote changes you haven’t seen, saving you the day a teammate pushes a commit to your branch.

2. Conflicts compound. If your edit to PR 1 collides with PR 2, you’ll resolve it during the PR 2 rebase. If it also collides with PR 3, you’ll resolve it again during PR 3.

3. If you see weird duplicate commits or unexpected conflicts, plain git rebase got confused about where PR 2 starts. Drop to the explicit form: git rebase --onto auth/01-users-table @{u} auth/02-auth-endpoint — replays only the commits that are on the remote PR 2 branch but not on the new PR 1.

Once you've manually cascaded a few times, the value clicks.

There are many tools out there that automate this part. Pick whichever tool matches your team's appetite for new tooling.

When to Use Stacked PRs (and When Not To)

Use them when:

• A feature naturally layers: schema → API → UI

• Any one part is large enough to deserve a focused review on its own

• You want to keep moving while reviews come in

• Your team has slow review cycles

Skip them when:

• The change is genuinely atomic (a one-line fix, a config update)

• The layers are so interdependent that splitting them adds noise instead of clarity

• The team has never done this and isn’t ready for the tooling overhead

The rule I use:

If a PR has more than ~300 lines of substantive logic, I ask whether it can be split.
Not every PR needs to be, but the question is worth asking every time.

Practical Tips for Getting Started

1. Start with the mental model, not the tooling. Do one stack by hand using the commands above. Feel the workflow. Understand why the tooling exists before installing it.

2. Name your branches clearly. Use a prefix pattern: auth/01-users-table, auth/02-api, auth/03-ui. The chain becomes visible without looking at the PR graph.

3. Write context-rich PR descriptions. Each PR should explain what it does in isolation, and where it sits in the stack. “This PR adds the schema. PR 2 adds the API. PR 3 adds the UI.” Reviewers should never have to reverse-engineer the intent.

4. Keep each PR independently runnable where you can. If PR 2 can be tested without PR 1 being merged — great. If not, say so in the description. The more each layer stands alone, the easier the reviews get.

5. Batch your feedback fixes. If PRs 1 and 2 both get comments, fix both before rebasing the stack. One cascading rebase beats two.

6. Use --force-with-lease, never --force. This is the one-line rule that saves you from clobbering a teammate’s commit.

The Culture Shift That Actually Matters

Tooling is secondary. The real shift is in how the team thinks about review.

Big PRs are a symptom of a team that has implicitly agreed that waiting is normal.

The author doesn’t want to open multiple PRs (more overhead). The reviewer doesn’t want to navigate a stack (more context).

Everyone tolerates the friction because it’s symmetric: everybody suffers the same way.

Stacked PRs break that. You do a bit more thinking upfront: splitting the work into layers. The reviewer gets a much easier job. Reviews come back faster, feedback is sharper, and merging hurts less.

Once you’ve shipped this way for a few weeks, the old workflow feels like trying to write a function with no return statement: technically possible, but you’re fighting the tool the whole way.

📌 TL;DR

• Stacked PRs break a feature into a chain of small, focused PRs, each one’s base branch is the PR below it

• They keep you unblocked: you keep building while reviews come in asynchronously

• The hard part is cascading rebases when an earlier layer changes; tooling solves this

• The workflow needs a small culture shift: many small PRs instead of a few big ones

• Do one stack manually before touching tooling, that’s how you learn what the tool is buying you

Thanks for reading, and stay awesome! 🙏

Follow me on LinkedIn | Twitter(X) | Threads

Thank you for supporting this newsletter.

Consider sharing this post with your friends and get rewards.

You are the best! 🙏

Share

Press the Like button if you found this post helpful

In Part 1, I covered the foundational mistakes: type safety, error handling, and architecture. The kind that shapes how your codebase grows.

This post covers the rest: the runtime and code quality mistakes that don't break your build but break your production. Code Hygiene, Async & Performance, Testing & Validation.

• Share this post & I’ll send you some rewards for the referrals.

Give Your AI Agent Eyes on the Web (Partner)

MCP servers eat 72% of your agent’s context window before it reads a single user message. There’s a simpler way.

Bright Data CLI gives coding agents like Claude Code, Cursor, and Copilot direct access to real-time web data - from the terminal. No MCP schema bloat. No server setup. Just one command:

brightdata scrape https://any-website.com → structured JSON

Scrape any URL with automatic CAPTCHA bypass. Search Google/Bing/Yandex. Extract structured data from 40+ platforms (Amazon, LinkedIn, Instagram, TikTok, YouTube, Reddit, and more).

One install. Works with 46+ AI agents. 10-32x cheaper than MCP for the same tasks.

⭐ Star on GitHub →

(Thanks to BrightData for partnering on this post.)

12. Mutating Function Parameters

interface Order {
  id: string;
  total: number;
  discountApplied?: boolean;
}

// ❌ Surprise mutation
function applyDiscount(order: Order, discount: number) {
  order.total *= 1 - discount / 100; // Mutates the original!
  order.discountApplied = true;
  return order;
}

The caller passes an order object and gets it back mutated. Every other reference to that object now sees the changed values. This creates action-at-a-distance bugs that are nearly impossible to trace.

The fix:

// ✅ Return a new object
function applyDiscount(order: Order, discount: number): Order {
  return {
    ...order,
    total: order.total * (1 - discount / 100),
    discountApplied: true,
  };
}

Functions that return new values instead of mutating inputs are easier to test, easier to reason about, and compose naturally.

Use readonly parameter types to enforce this at compile time.

13. Leaking Memory with Uncleared Listeners, Timers, and Subscriptions

// ❌ Event listener that outlives the thing it's attached to
class WebSocketManager {
  private ws?: WebSocket;
  private handleMessage = (event: MessageEvent) => { /* ... */ };
  private handleError = (event: Event) => { /* ... */ };

  connect(url: string) {
    this.ws = new WebSocket(url);
    this.ws.addEventListener("message", this.handleMessage);
    this.ws.addEventListener("error", this.handleError);

    // Health check every 30 seconds — but nobody ever stops it
    setInterval(() => this.ping(), 30_000);
  }

  ping() { /* ... */ }
}

The setInterval runs forever. The event listeners hold references to this, keeping the entire class instance (and everything it references) alive in memory.

Multiply this by reconnections and you’ve got a slow leak that crashes your Node.js process at 3am on a Saturday.

The tricky part: memory leaks don’t show up in tests. They show up after hours or days of uptime.

If your Node.js process memory keeps climbing when traffic is flat, run node --inspect and take heap snapshots 5 minutes apart — growing object counts point straight at the leak.

The fix:

// ✅ Track everything. Clean up everything.
class WebSocketManager {
  private ws?: WebSocket;

  // Arrow-function class fields: auto-bound `this` AND stable references
  // so removeEventListener can actually find them.
  private handleMessage = (event: MessageEvent) => { /* ... */ };
  private handleError = (event: Event) => { /* ... */ };
  private pingInterval?: ReturnType<typeof setInterval>;

  connect(url: string) {
    this.ws = new WebSocket(url);
    this.ws.addEventListener("message", this.handleMessage);
    this.ws.addEventListener("error", this.handleError);
    this.pingInterval = setInterval(() => this.ping(), 30_000);
  }

  disconnect() {
    this.ws?.removeEventListener("message", this.handleMessage);
    this.ws?.removeEventListener("error", this.handleError);
    clearInterval(this.pingInterval);
    this.ws?.close();
  }

  ping() { /* ... */ }
}

Every addEventListener needs a removeEventListener. Every setInterval needs a clearInterval. Every subscription needs an unsubscribe.

If your class has a connect or start — it needs a disconnect or stop. No exceptions.

One snag worth flagging: removeEventListener only removes a handler when you pass the same function reference that was added. Regular methods don’t auto-bind.

If you write addEventListener("message", this.handleMessage.bind(this)), the .bind returns a new function each time and the removal silently no-ops.

Arrow-function class fields (shown above) give you both a stable reference and a this that points at the instance.

14. Never Cancelling Async Operations

// ❌ Fetch that can't be stopped
async function searchUsers(query: string) {
  const response = await fetch(`/api/users?q=${query}`);
  return response.json();
}

// User types "al", "ali", "alic", "alice" — 4 requests fly out
// The response for "al" might arrive AFTER "alice"
// Now your UI shows results for "al" while the search box says "alice"

No cancellation means wasted requests, race conditions, and stale data rendering on screen.

In React, this is the #1 cause of "my component shows old data" bugs.

The fix:

// ✅ AbortController — the native cancellation primitive
function searchUsers(query: string, signal?: AbortSignal) {
  return fetch(`/api/users?q=${query}`, { signal }).then((r) => r.json());
}

// In the caller — cancel the previous request before starting a new one
let controller: AbortController | null = null;

function onSearchChange(query: string) {
  controller?.abort(); // Cancel whatever's in flight
  controller = new AbortController();

  searchUsers(query, controller.signal)
    .then(setResults)
    .catch((err) => {
      if (err.name !== "AbortError") throw err; // Ignore expected aborts
    });
}

AbortController works with fetch, Node.js streams, database drivers, and most async APIs.

In React, use it inside useEffect cleanup.

In Node.js, pass it to long-running operations so callers can cancel them.

For CPU-bound or polling code that doesn't natively accept a signal, check signal.aborted between iterations and bail out early. If your async function doesn't accept a signal, it's a foot-gun waiting to fire.

15. No HTTP / fetch Timeouts

// ❌ A fetch with no timeout is a fetch that can hang forever
async function getUser(id: string) {
  const response = await fetch(`/api/users/${id}`);
  return response.json();
}

fetch has no default timeout. If the upstream service is slow or hung, the request waits indefinitely.

On a server under load, that means every slow request consumes a connection and a chunk of your concurrency budget — slow upstreams cascade into your service hanging too.

Same shape on the client: the spinner spins forever and the user reloads the tab.

The fix:

// ✅ AbortSignal.timeout — the modern, native way
async function getUser(id: string) {
  const response = await fetch(`/api/users/${id}`, {
    signal: AbortSignal.timeout(5000), // 5s — fails fast if the server doesn't respond
  });
  return response.json();
}

AbortSignal.timeout(ms) (Node 17.3+, all modern browsers) returns a signal that aborts itself after the timeout. Combine with the cancellation pattern from #14 using AbortSignal.any([userSignal, AbortSignal.timeout(5000)]) when you want both user cancellation and a hard ceiling.

Pick a timeout for every outbound HTTP call.

The right value depends on the operation: 2–5 seconds for user-facing reads, 30+ seconds for bulk imports, but never “no limit”.

A “missing” timeout is the silent default that bites you under load.

16. Running Independent Async Operations Sequentially

// ❌ Sequential — total time = sum of all operations
const user = await getUser(id);
const orders = await getOrders(id);
const notifications = await getNotifications(id);
// If each takes 200ms, total = 600ms

If the operations don’t depend on each other, running them sequentially wastes time.

The fix:

// ✅ Parallel — total time = slowest operation
const [user, orders, notifications] = await Promise.all([
  getUser(id),
  getOrders(id),
  getNotifications(id),
]);
// If each takes 200ms, total = 200ms

Use Promise.all when all operations must succeed. Use Promise.allSettled when some can fail independently — like loading a dashboard where each widget fetches its own data.

Keep sequential await for operations where each step depends on the previous one.

One related foot-gun related to this:

Don’t use arr.forEach(async ...) for any of this!

forEach ignores the promise its callback returns, so you fire N parallel async calls and the function returns before any of them complete, including writes that haven’t happened yet.

Logs say “done”; the database says otherwise.

Use Promise.all(arr.map(...)) for parallel, or for...of with await for sequential.

17. Blocking the Event Loop

// ❌ Sync I/O on a hot path — the entire process freezes here
import fs from "node:fs";

app.get("/config", (req, res) => {
  const config = fs.readFileSync("./config.json", "utf8"); // blocks!
  res.json(JSON.parse(config));
});

// ❌ Heavy CPU work on the main thread
app.post("/report", (req, res) => {
  const csv = generateMassiveCsv(req.body); // 800ms of pure CPU
  res.send(csv);
});

Node.js runs your code on a single thread. While that thread is busy, nothing else runs — no other requests, no timers, no I/O callbacks. A 200ms sync read or a 500ms JSON.parse on a fat payload pauses every concurrent user of your service. Under any real load this looks like random latency spikes that nobody can reproduce locally.

The usual offenders: fs.readFileSync, crypto.pbkdf2Sync, child_process.execSync, parsing huge JSON or XML payloads, regex with catastrophic backtracking, and tight loops over big arrays.

The fix:

// ✅ Async I/O — the event loop keeps serving other requests
import fs from "node:fs/promises";

app.get("/config", async (req, res) => {
  const config = await fs.readFile("./config.json", "utf8");
  res.json(JSON.parse(config));
});

// ✅ Move CPU-heavy work off the main thread
import { Worker } from "node:worker_threads";

app.post("/report", async (req, res) => {
  const worker = new Worker("./csv-worker.js", { workerData: req.body });
  worker.once("message", (csv) => res.send(csv));
});

For I/O, the rule is simple: never use the *Sync variant in request-handling code.

For CPU-heavy work, move it to a worker thread (worker_threads) or a background queue (BullMQ, etc.). For regex, audit any pattern that contains nested quantifiers ((a+)+) — those are how a 50-char user input becomes a 30-second freeze.

How to spot it in production:

enable Node’s built-in perf_hooks.monitorEventLoopDelay() or watch for event_loop_lag in your APM.

A loop delay above ~50ms during normal traffic means something is blocking, and it’s almost always one of the patterns above.

18. Using Date for Everything

// ❌ Timezone roulette
const meetingTime = new Date("2024-03-15T10:00:00");
// What timezone is this? The answer: it depends on where the code runs.

JavaScript's Date always represents an instant (UTC milliseconds), but parsing a date-time string without an offset uses the local timezone of the machine running the code. Engines agree on this, that's the spec. The problem is that your machines disagree on what "local" means:

// Your server (UTC): parses as 2024-03-15T10:00:00.000Z
// Your laptop (UTC+2): parses as 2024-03-15T10:00:00.000+02:00 → 08:00 UTC
// Your US colleague (UTC-5): parses as 2024-03-15T10:00:00.000-05:00 → 15:00 UTC
// Same string, three different instants in time.

Store that in a database, render it for a user in Tokyo, and you’ve got a meeting that nobody shows up to at the right time.

The fix:

// ✅ Use Temporal (shipping in Firefox, polyfill elsewhere) or date-fns with explicit timezones
import { Temporal } from "@js-temporal/polyfill";

const meeting = Temporal.ZonedDateTime.from({
  year: 2024,
  month: 3,
  day: 15,
  hour: 10,
  minute: 0,
  timeZone: "Europe/Sofia",
});

// ✅ Or with date-fns v3+ (lighter weight, no polyfill needed)
import { TZDate } from "@date-fns/tz";

const meetingInSofia = new TZDate("2024-03-15T10:00:00", "Europe/Sofia");

Check your support matrix before you drop the Temporal polyfill.

If Temporal feels too heavy, date-fns with @date-fns/tz is solid and tree-shakeable.

The point isn't which library. It's that you pick one that forces timezone-awareness instead of letting Date guess.

19. Testing for Coverage, Not for Value

// ❌ 100% coverage, 0% confidence
it("should create an instance", () => {
  const service = new UserService(mockDeps);
  expect(service).toBeDefined(); // Yes... constructors construct things
});

it("should call the database", async () => {
  await service.getUser("123");
  expect(mockDb.findById).toHaveBeenCalledWith("123");
  // Congrats, you've tested that your code... calls code
});

These tests verify implementation details, not behavior.

They break on every refactor and catch zero bugs. (Spy assertions like toHaveBeenCalledWith are fine alongside behavior assertions, for example, when you need to verify a side effect on a mocked dependency. They’re not fine as a substitute.)

The fix: Test behavior. What comes out given what goes in?

// ✅ Tests that verify behavior
it("returns the user when found", async () => {
  mockDb.findById.mockResolvedValue({ id: "123", name: "Alice" });
  const user = await service.getUser("123");
  expect(user).toEqual({ id: "123", name: "Alice" });
});

it("throws NotFoundError when user does not exist", async () => {
  mockDb.findById.mockResolvedValue(null);
  await expect(service.getUser("123")).rejects.toThrow(NotFoundError);
});

it("applies discount correctly", () => {
  expect(calculateDiscount(100, "SAVE20")).toBe(80);
  expect(calculateDiscount(100, "INVALID")).toBe(100);
  expect(calculateDiscount(0, "SAVE20")).toBe(0);
});

Test the contract, not the implementation.
A good test should survive a refactor that doesn't change behavior.

20. Not Validating Input at the Boundary

// ❌ Trust-based programming
app.post("/users", async (req, res) => {
  const user = await db
    .insertInto("users")
    .values(req.body) // Whatever you send, we store
    .returningAll()
    .executeTakeFirstOrThrow();
  res.json(user);
});

req.body could be anything. A missing field crashes your database query. An extra field like { role: 'admin' } silently grants privilege escalation. That’s classic mass assignment, and it’s the single most common way one of these handlers becomes a security incident.

(Prototype pollution via __proto__ is a separate concern with its own mitigations, but mass assignment is what you’ll actually see in production logs.)

The fix: Validate at the edge, trust internally.

import { z } from "zod";

const CreateUserSchema = z.object({
  name: z.string().min(1).max(100),
  email: z.string().email(),
  role: z.enum(["admin", "user"]).default("user"),
});

app.post("/users", async (req, res) => {
  const input = CreateUserSchema.parse(req.body);
  // input is typed and validated — only the fields you defined, nothing extra
  const user = await db
    .insertInto("users")
    .values(input)
    .returningAll()
    .executeTakeFirstOrThrow();
  res.json(user);
});

Zod gives you runtime validation and TypeScript types from a single schema definition. The .parse() call strips unknown fields by default, so no mass assignment attacks.

Validate at every boundary: API routes, queue consumers, webhook handlers, file parsers.

Once data passes validation, trust it downstream:
=> No defensive checks scattered through your business logic.

One pairing worth naming: input validation (this section) and parameterized queries (the Kysely .values(input) call above parameterizes for you) solve different attacks — mass assignment vs. SQL injection.

They’re complementary, not interchangeable; both belong at the boundary, never in your business logic.

Note: SQL injection deserves its own deep dive, which I’ll cover in a future post.

📌 TL;DR

In this post, we covered:

• Code Hygiene: parameter mutation

• Async & Performance: memory leaks, cancellation, HTTP timeouts, sequential operations, blocking the event loop, Date

• Testing & Validation: coverage vs. value, input validation

If you missed Part 1, start there. It covers the foundational mistakes in type safety, error handling, and architecture that shape everything else.

Thanks for reading, and stay awesome!

Follow me on LinkedIn | Twitter(X) | Threads

Thank you for supporting this newsletter.

Consider sharing this post with your friends and get rewards.

You are the best! 🙏

Share

Press the Like button if you found this post helpful

Every JS/TS codebase collects the same kinds of mistakes.

They don’t break the build. They don’t fail tests. They rarely show up in PR review. They just sit there, quietly making every change a little more expensive, until one of them surfaces as a production incident at 2am.

I’ve hit every one of these across 9+ years of shipping JavaScript and TypeScript. Twenty in total, too many for one post, so I split them into two parts.

This post covers the foundations: how you model types, how you handle errors, and how you shape your modules. Get these wrong and everything you build on top compounds the pain.

Share this post & I’ll send you some rewards for the referrals.

Issues that fix themselves? (Sentry Seer, Partner)

Seer is Sentry’s AI debugging agent. It uses everything Sentry knows (errors, traces, logs, replays, profiles, and your code) to automatically fix production issues, investigate problems alongside you, and predict bugs before they ship.

Every error Sentry captures comes with a stack trace, a span tree, a breadcrumb trail, session replay, profiles, logs, and the surrounding code. Seer is a reasoning layer built specifically for debugging and wired directly into all of that telemetry.

Other AI tools can help you write code or search docs. Seer understands why your app is broken.

• Autofix kicks in directly on issues in Sentry and in your Slack alerts.

• Seer Agent lets you investigate proactively—ask questions, explore patterns, dig into incidents conversationally.

• AI Code Review catches bugs before they ship, scanning PRs against production behavior.

• Sentry’s MCP brings Seer’s context directly into your coding agent (Cursor, Copilot, Claude) in your editor or terminal.

Try For Free

PS: Use the tshapeddev promo code to get 3 months free on the Team plan of Sentry for any new accounts.

(Thanks to Sentry for partnering on this post.)

1. Not Enabling TypeScript Strict Mode

// tsconfig.json — the default sin
{
  "compilerOptions": {
    "strict": false // or just not setting it
  }
}

Without strict mode, TypeScript silently allows null where you expect a string, undefined where you expect an object, and implicit any on every untyped parameter. You get half the type safety and all of the tooling overhead.

The fix:

{
  "compilerOptions": {
    "strict": true
  }
}

This enables strictNullChecks, noImplicitAny, strictFunctionTypes, and more.

Yes, migrating an existing project hurts. Do it anyway. Enable strict flags incrementally if you must, but strictNullChecks alone prevents more runtime errors than everything else combined.

2. Using any as an Escape Hatch

// ❌ The "make TypeScript shut up" approach
function processData(data: any) {
  return data.items.map((item: any) => item.name.toUpperCase());
}

any disables type checking entirely. It’s contagious. Once any enters a chain, everything downstream is unchecked. You’ve just written JavaScript with extra build steps.

The fix:

// ✅ Use unknown + a type guard to narrow
function isValidResponse(data: unknown): data is { items: { name: string }[] } {
  if (typeof data !== "object" || data === null) return false;
  const maybe = data as { items?: unknown };
  if (!Array.isArray(maybe.items)) return false;
  return maybe.items.every(
    (item) =>
      typeof item === "object" &&
      item !== null &&
      typeof (item as { name?: unknown }).name === "string",
  );
}

function processData(data: unknown): string[] {
  if (!isValidResponse(data)) {
    throw new Error("Invalid data format");
  }
  // After the guard, TypeScript knows data.items exists and is typed
  return data.items.map((item) => item.name.toUpperCase());
}

// Or use generics when the type is truly variable
function firstElement<T>(arr: T[]): T | undefined {
  return arr[0];
}

unknown is the type-safe cousin of any. It forces you to narrow before accessing properties.

Type guards (the data is X return type, also called a type predicate) teach the compiler what shape to expect after the check.

Important: the compiler takes your word for it. If the guard body doesn't actually verify every field you claim, you get a typed lie.

For non-trivial shapes, reach for a schema library like Zod instead of hand-rolling guards.

Use generics when you need flexibility. Reserve any for genuinely untyped boundaries (third-party libs with no types), and mark those with // eslint-disable-next-line @typescript-eslint/no-explicit-any.

3. Not Using Discriminated Unions

// ❌ Optional field soup
interface ApiResponse {
  data?: UserData;
  error?: string;
  loading?: boolean;
}

// Is this valid? { data: undefined, error: "fail", loading: true }
// What about { data: someData, error: "also fail" }?
// The type allows both. Your runtime won't.

The fix:

// ✅ Discriminated union — each state is explicit
type ApiResponse =
  | { status: 'loading' }
  | { status: 'success'; data: UserData }
  | { status: 'error'; error: string };

function handleResponse(response: ApiResponse) {
  switch (response.status) {
    case 'loading':
      return <Spinner />;
    case 'success':
      return <UserProfile data={response.data} />;  // data is guaranteed
    case 'error':
      return <ErrorBanner message={response.error} />;  // error is guaranteed
  }
}

Discriminated unions make impossible states unrepresentable. TypeScript automatically narrows the type in each branch; no null checks needed.

4. Ignoring Return Types on Exported Functions

// ❌ No return type — the API contract is implicit
export async function getUser(id: string) {
  const user = await db
    .selectFrom("users")
    .where("id", "=", id)
    .selectAll()
    .executeTakeFirst();
  if (!user) throw new NotFoundError("User not found");
  return user;
}

TypeScript infers the return type, but the inference is tied to the implementation.

Change how you query the database and the return type silently changes, breaking every caller without a compile error.

The fix:

// ✅ Explicit return type on exported functions
export async function getUser(id: string): Promise<User> {
  const user = await db
    .selectFrom("users")
    .where("id", "=", id)
    .selectAll()
    .executeTakeFirst();
  if (!user) throw new NotFoundError("User not found");
  return user;
}

Explicit return types on exported functions serve as a contract. If the implementation changes in a way that breaks the contract, the function itself errors, not every downstream consumer.

Rule of thumb: always type exports. Let inference handle private/local functions.

5. Catching Errors and Swallowing Them

// ❌ The silent failure
try {
  await processPayment(order);
} catch (error) {
  console.log("Payment failed");
  // Cool, so... now what?
}

The order continues as if payment succeeded. The user gets charged nothing. You get no alert. The bug sits in production for weeks until someone checks the logs.

The fix: every catch block needs exactly one strategy.

Here are your three options (pick one, not all):

// ✅ Strategy A — Rethrow (let the caller decide)
try {
  await processPayment(order);
} catch (error) {
  logger.error("Payment failed", { orderId: order.id, error });
  throw error;
}

// ✅ Strategy B — Recover (handle it yourself)
try {
  await processPayment(order);
} catch (error) {
  logger.error("Payment failed", { orderId: order.id, error });
  await markOrderAsPendingPayment(order.id);
  await notifyPaymentTeam(order.id);
}

// ✅ Strategy C — Transform into a domain error
try {
  await processPayment(order);
} catch (error) {
  logger.error("Payment failed", { orderId: order.id, error });
  throw new PaymentFailedError(order.id, { cause: error });
}

“Log and continue” is almost never the right answer. If you’re not rethrowing, recovering, or transforming, you’re hiding bugs.

Strategy D: Make errors impossible to ignore with the Result pattern.

try/catch has a design flaw — nothing forces the caller to handle the error.

The Result pattern encodes success and failure in the return type itself. You can’t access the data without checking first.

// ✅ Result type — errors are values, not exceptions
type Result<T, E = Error> = { ok: true; value: T } | { ok: false; error: E };

async function processPayment(
  order: Order,
): Promise<Result<Receipt, PaymentError>> {
  try {
    const receipt = await stripe.charges.create({ /* ... */ });
    return { ok: true, value: receipt };
  } catch (err) {
    return { ok: false, error: new PaymentError(order.id, { cause: err }) };
  }
}

// The caller CAN'T ignore the error — TypeScript won't let you access .value without checking .ok
const result = await processPayment(order);
if (!result.ok) {
  await markOrderAsPendingPayment(order.id);
  return;
}
sendConfirmation(result.value);  // result.value is typed as Receipt here

This works great for operations where failure is expected and the caller should decide what to do, like payments, validation, external API calls.

Save try/catch for truly exceptional cases (database down, out of memory).

Use Result for “this might not work and that’s fine”.

6. Not Handling Promise Rejections

// ❌ Fire and forget
app.post("/webhook", (req, res) => {
  processWebhook(req.body); // Returns a Promise — but nobody awaits it
  res.sendStatus(200);
});

If processWebhook throws, you get an unhandled rejection.

In Node.js 15+, that crashes the process. Even with a global handler, you’ve lost the request context.

The fix:

// ✅ Always await or explicitly handle
app.post("/webhook", async (req, res, next) => {
  try {
    await processWebhook(req.body);
    res.sendStatus(200);
  } catch (error) {
    next(error);  // Let Express error handler deal with it
  }
});

// If you truly need fire-and-forget:
processWebhook(req.body).catch((error) => {
  logger.error("Webhook processing failed", { error });
});

Rule: every Promise either gets awaited or gets a .catch(). No exceptions.

7. Hardcoding Dependencies Instead of Injecting Them

// ❌ Welded to implementations
import { db } from "../lib/db";
import { sendEmail } from "../lib/email";

export async function createOrder(data: CreateOrderInput) {
  const order = await db
    .insertInto("orders")
    .values(data)
    .returningAll()
    .executeTakeFirstOrThrow();
  await sendEmail(order.email, "Confirmed", template(order));
  return order;
}

This function is impossible to unit test without jest.mock('../lib/db'), and the moment you rename that file or move it, every mock breaks. You end up testing your mock wiring, not your business logic.

The fix:

// ✅ Dependencies come from the outside
interface OrderServiceDeps {
  db: Database;
  email: EmailService;
}

export function createOrderService({ db, email }: OrderServiceDeps) {
  return {
    async createOrder(data: CreateOrderInput) {
      const order = await db.orders.create(data);
      await email.send(order.email, "Confirmed", template(order));
      return order;
    },
  };
}

Now testing is trivial: pass in fakes. No jest.mock, no module path fragility. Wire real implementations at the entry point.

(For a deep dive, see Dependency Injection in Node.js & TypeScript. The Part Nobody Teaches You)

8. Over-Engineering with Microservices Too Early

// ❌ 3 developers, 500 users, and this repo structure:
api-gateway/          ← own Docker, CI/CD, database
user-service/         ← own Docker, CI/CD, database
order-service/        ← own Docker, CI/CD, database
payment-service/      ← own Docker, CI/CD, database
notification-service/ ← own Docker, CI/CD, database
// 5 deploys, 5 sets of logs, 5 things to debug at 2am

You’re spending more time debugging network calls between your own services than building features. Every “simple” change touches three repos and needs coordinated deploys.

The fix: Start with a modular monolith. Same domain boundaries, one deploy.

// ✅ Modular monolith — clear boundaries, zero network overhead
src/
  modules/
    users/        # own routes, service, repository, schema
    orders/       # own routes, service, repository, schema
    payments/     # own routes, service, repository, schema
    notifications/# own routes, service, repository, schema
  shared/         # cross-module types, utils, middleware

Each module owns its slice of the database and exposes a clean interface. No module reaches into another’s tables. When (not if) you need to extract a module into a service, the boundary is already there — it’s a deployment change, not a rewrite.

Extract to services only when you have a concrete scaling bottleneck — not because a conference talk said microservices are the future. Most teams that “need microservices” actually need better module boundaries in their monolith.

9. Writing 100+ Line Functions

// ❌ The god function
export async function handleCheckout(req: Request, res: Response) {
  // Validate input (20 lines)
  // Check inventory (15 lines)
  // Calculate pricing (25 lines)
  // Apply discount codes (20 lines)
  // Process payment (15 lines)
  // Create order (10 lines)
  // Send confirmation (10 lines)
  // Update analytics (10 lines)
  res.json({ orderId: order.id });
}

The fix: Extract each block into a named function, not for reuse, but for readability.

export async function handleCheckout(req: Request, res: Response) {
  const input = validateCheckoutInput(req.body);
  await checkInventory(input.items);
  const pricing = calculatePricing(input.items, input.discountCode);
  const charge = await processPayment(pricing, input.paymentMethod);
  const order = await createOrder(input, pricing, charge);
  await sendConfirmation(order);
  trackCheckout(order);
  res.json({ orderId: order.id });
}

Each function name tells you what happens. You can read the checkout flow in 10 seconds without scrolling through 125 lines of implementation.

10. Putting Business Logic in Controllers

// ❌ Controller knows too much
app.post("/orders", async (req, res) => {
  const items = req.body.items;
  let total = 0;
  for (const item of items) {
    const product = await db
      .selectFrom("products")
      .where("id", "=", item.productId)
      .selectAll()
      .executeTakeFirstOrThrow();
    if (product.stock < item.quantity) {
      return res.status(400).json({ error: "Out of stock" });
    }
    total += product.price * item.quantity;
  }
  if (req.body.discountCode) {
    const discount = await db
      .selectFrom("discounts")
      .where("code", "=", req.body.discountCode)
      .selectAll()
      .executeTakeFirstOrThrow();
    total *= 1 - discount.percentage / 100;
  }
  const order = await db
    .insertInto("orders")
    .values({ items, total, userId: req.user.id })
    .returningAll()
    .executeTakeFirstOrThrow();
  res.json(order);
});

Now your business rules are trapped in an HTTP handler. Can’t reuse them for a CLI, a queue consumer, or a GraphQL resolver.

The fix: Controllers do three things: parse input, call a service, format output.

// Controller — thin
app.post("/orders", async (req, res) => {
  const input = parseCreateOrderInput(req.body);
  const order = await orderService.createOrder(input, req.user.id);
  res.json(formatOrderResponse(order));
});

// Service — contains business logic
class OrderService {
  async createOrder(input: CreateOrderInput, userId: string) {
    await this.validateInventory(input.items);
    const total = this.calculateTotal(input.items, input.discountCode);
    return this.db.orders.create({ ...input, total, userId });
  }
}

11. Circular Dependencies Between Modules

// ❌ user.ts imports order.ts, order.ts imports user.ts
// user.ts
import { Order } from "./order";
export class User {
  orders: Order[] = [];
}

// order.ts
import { User } from "./user";
// Module top-level use of the cyclic import — User is still undefined here
// because user.ts hasn't finished evaluating yet.
export class Order extends User {}
// 💥 TypeError: Class extends value undefined is not a constructor or null

Circular imports are silent killers.

When the runtime hits a cycle, it hands the second module a half-initialized copy of the first. The bindings exist, but their values are still undefined.

Use those bindings at the module top level (extends, new, calling a function, reading a constant) and you get a crash. Use them only inside a method body, and it usually "works", until someone adds a top-level reference and the file blows up on import.

The stack trace rarely points to the real cause.

The fix:

// ✅ Option 1: Extract the shared contract into a third module
// types.ts
export interface IUser { name: string; orders: IOrder[]; }
export interface IOrder { owner: IUser; }

// user.ts — depends on types, not on order.ts
import { IOrder } from "./types";
export class User implements IUser {
  name!: string;
  orders: IOrder[] = [];
}

// order.ts — depends on types, not on user.ts
import { IUser } from "./types";
export class Order implements IOrder {
  owner!: IUser;
}

// ✅ Option 2: Break the cycle by inverting the dependency direction.
// "Lower-level" modules shouldn't reach up into "higher-level" ones.
// Orders don't need the whole User — pass what they actually use.
export class Order {
  constructor(public ownerName: string) {}
}

If two modules import each other, one of them knows too much. Fix the dependency direction or extract the shared contract into a third module.

Types alone (interface, type) are erased at compile time and don’t cause runtime cycles, so moving the shared types into a separate file is the cheapest way out.

Turn on eslint-plugin-import‘s no-cycle rule so new cycles fail CI instead of hiding until the wrong person imports the wrong file.

📌 TL;DR

In this post (Part 1), we’ve covered the foundational mistakes that shape everything else:

• Type Safety: strict mode, any, discriminated unions, return types.

• Error Handling: swallowing errors, unhandled rejections, the Result pattern.

• Architecture & Design: dependency injection, microservices, long functions, controllers, circular deps.

In Part 2, we will cover runtime and quality mistakes that bite you in production like Code Hygiene, Async & Performance, Testing & Validation.

Thanks for reading, and stay awesome!

Follow me on LinkedIn | Twitter(X) | Threads

Thank you for supporting this newsletter.

Consider sharing this post with your friends and get rewards.

You are the best! 🙏

Share

Press the Like button if you found this post helpful

• Share this post & I’ll send you some rewards for the referrals.

ES2025 is finalized. You’ve probably seen the listicles.

Here’s what’s different about this one: I took features from the spec and ran them against code I’ve written in the past year.

Some are genuinely useful. Others are niche enough that you’ll forget they exist in a month.

Let’s separate what matters from what doesn’t.

The tax you pay to run multiple agents. Cline Kanban (Partner)

If you’ve spent any time with coding agents, you know the feeling. You start the morning with a clean plan. Spin up a few agents. One is refactoring the auth module. Another is writing tests. A third is scaffolding a new API endpoint. You’re flying.

Then, around 10:30 AM, you look up and realize you have 20 terminal windows open. One agent is blocked waiting for a decision you forgot to make. Another finished 40 minutes ago, and you never noticed. A third went sideways three commits back. You’re no longer flying. You’re drowning.

You’ve shifted from human as driver to human as director. When running coding agents in parallel, the bottleneck isn’t just context. It’s your own attention trying to manage 10 agents across 10 terminals. You’re losing your mind to terminal chaos.

Meet Cline Kanban, a CLI-agnostic visual orchestration layer that makes multi-agent workflows usable across providers. Multiple agents, one UI. It’s the air traffic controller for the agents you’re already running, regardless of where they live.

• Interoperable: Claude Code and Codex compatible, with more coming soon.

• Full Visibility: Confidently run multiple agents and work through your backlog faster.

• Smart Triage: See which agents are blocked or in review and jump in to unblock them.

• Chain Tasks: Set dependencies so Agent B won’t start until Agent A is complete.

• Familiar UI: Everything in a single Kanban view.

Stop tracking agents and start directing them. Get a meaningful edge with the beta release.

Install Cline Kanban Today: npm i -g cline

Get Started Today

(Thanks to Cline Kanban for partnering on this post.)

1. Set Methods

Sets have been half-baked since ES6.

You could create them, add to them, and check membership.

However, if you wanted to intersect, union, or diff two sets, you had to write it yourself or reach for lodash.

Not anymore.

Before:

function intersect<T>(a: Set<T>, b: Set<T>): Set<T> {
  const result = new Set<T>();
  for (const item of a) {
    if (b.has(item)) result.add(item);
  }
  return result;
}

const allowedRoles = new Set(['admin', 'editor', 'viewer']);
const userRoles = new Set(['editor', 'commenter']);
const effectiveRoles = intersect(allowedRoles, userRoles);

After:

const allowedRoles = new Set(['admin', 'editor', 'viewer']);
const userRoles = new Set(['editor', 'commenter']);
const effectiveRoles = allowedRoles.intersection(userRoles);
// Set {'editor'}

The full list: .intersection(), .union(), .difference(), .symmetricDifference(), .isSubsetOf(), .isSupersetOf(), .isDisjointFrom().

These are immutable. They return new Sets. That’s the right call.

If you’re doing any kind of permissions, feature flags, or tag filtering, this cleans up real code today. TypeScript support landed in 5.5.

2. Promise.withResolvers(), Externalized Control

Ever needed to create a promise and resolve it from outside the executor callback?

You’ve probably written this pattern dozens of times:

Before:

let resolve: (value: string) => void;
let reject: (reason: Error) => void;

const promise = new Promise<string>((res, rej) => {
  resolve = res;
  reject = rej;
});

// Later, somewhere else...
eventEmitter.on('data', (data) => resolve(data));
eventEmitter.on('error', (err) => reject(err));

After:

const { promise, resolve, reject } = Promise.withResolvers<string>();

eventEmitter.on('data', (data) => resolve(data));
eventEmitter.on('error', (err) => reject(err));

No more dangling let declarations. No more praying that resolve was assigned before someone calls it.

Any time you’re bridging between callback/event-based code and promises, like WebSocket message handlers, test utilities, and manual coordination. This approach is cleaner.

TypeScript has supported it since 5.4.

3. Iterator.prototype Methods, Lazy Pipeline Operations

Arrays have had .map(), .filter(), .reduce() forever.

But iterators, the things you get from generators, Map.keys(), Set.values(), had nothing. You’d spread them into arrays just to use basic operations.

Before:

function* generateUsers(): Generator<User> {
  // yields users from a paginated API
}

// Wasteful: materializes entire iterator into memory
const activeEmails = [...generateUsers()]
  .filter(user => user.isActive)
  .map(user => user.email)
  .slice(0, 10);

After:

const activeEmails = generateUsers()
  .filter(user => user.isActive)
  .map(user => user.email)
  .take(10)
  .toArray();

The key difference: the new version is lazy. It only processes elements as needed. When .take(10) has enough, it stops. No intermediate arrays. No wasted work.

Available methods: .map(), .filter(), .take(), .drop(), .flatMap(), .reduce(), .toArray(), .forEach(), .some(), .every(), .find().

If you work with generators, streams, or any large datasets where you don’t want to materialize everything into an array first, this is a significant improvement.

TypeScript support: 5.6+.

4. RegExp.escape(), The One We’ve Been Waiting 15 Years For

If you’ve ever built a regex from user input, you’ve either used a library or written a janky escape function that probably misses edge cases.

Before:

// Did you remember all the special chars?
function escapeRegex(str: string): string {
  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
}

const searchTerm = 'price: $5.00 (USD)';
const pattern = new RegExp(escapeRegex(searchTerm), 'i');

After:

const searchTerm = 'price: $5.00 (USD)';
const pattern = new RegExp(RegExp.escape(searchTerm), 'i');

It’s a small thing, but it removes a class of bugs.

Any time you’re building dynamic regex patterns from external input (search, filtering, highlighting), use this.

5. Float16Array, Typed Array for ML and Graphics

A new typed array for 16-bit floating point numbers. Half the memory of Float32Array.

const weights = new Float16Array([0.5, -0.3, 0.8, 0.1]);
// Half the memory of Float32Array for the same data

If you’re doing ML inference in the browser, WebGPU work, or processing large numeric datasets where memory matters more than precision, this is useful.

For everyone else, you’ll never touch it.

But it’s good that the platform supports it. This means less reason to drop to WASM for numeric work.

6. using / await using, Automatic Cleanup

If you’ve ever forgotten to close a file handle, release a database connection, or clear a timer, this one’s for you.

Explicit Resource Management adds using and await using declarations that automatically call a cleanup function when the variable goes out of scope.

Think Python’s with statement or C#’s using. JavaScript finally has it.

Before:

async function exportReport(reportId: string) {
  const connection = await db.connect();
  try {
    const cursor = await connection.query(`SELECT * FROM reports WHERE id = $1`, [reportId]);
    try {
      const file = await fs.open('./report.csv', 'w');
      try {
        for await (const row of cursor) {
          await file.write(formatCsvRow(row));
        }
      } finally {
        await file.close();
      }
    } finally {
      await cursor.close();
    }
  } finally {
    await connection.release();
  }
}

After:

async function exportReport(reportId: string) {
  await using connection = await db.connect();
  await using cursor = await connection.query(`SELECT * FROM reports WHERE id = $1`, [reportId]);
  await using file = await fs.open('./report.csv', 'w');

  for await (const row of cursor) {
    await file.write(formatCsvRow(row));
  }
  // connection, cursor, and file are all released automatically
}

The nested try/finally pyramid is gone. Each resource cleans itself up when the block exits, whether it completes normally or throws.

For this to work, the resource needs a [Symbol.asyncDispose]() method (or [Symbol.dispose]() for synchronous resources).

Node.js built-ins like file handles already support it.

For your own classes, it’s straightforward:

class DatabaseConnection {
  async [Symbol.asyncDispose]() {
    await this.release();
  }
}

V8 and Node.js 22+ ship it. Browser support is still catching up: Chrome has it, Firefox and Safari are behind.

TypeScript supports it in 5.2+.

If you’re writing server-side code, start using this today. For client-side, wait a bit longer.

7. Promise.try(), Safe Function Wrapping

You have a function. It might be sync. It might be async. You want to call it and always get a Promise back, with errors caught either way.

Before:

function runTask(task: () => unknown): Promise<unknown> {
  try {
    const result = task();
    return Promise.resolve(result);
  } catch (err) {
    return Promise.reject(err);
  }
}

Or the shorter-but-subtle version:

// This doesn't catch synchronous throws from task()
const result = Promise.resolve().then(() => task());

After:

const result = Promise.try(task);

One line. Catches sync throws. Wraps sync return values. Passes through Promises. Does the right thing every time.

This shows up anywhere you accept a callback that could be sync or async, like plugin systems, middleware chains, test runners, task queues.

It’s the Promise.withResolvers of error handling: a small API that eliminates a whole class of subtle bugs.

Supported in Chrome 128+, Firefox 132+, Safari 18.2+, Node.js 22+. TypeScript 5.7+.

8. JSON modules and import attributes

Import attributes (the with syntax) let you specify how an import should be interpreted:

import config from './config.json' with { type: 'json' };
import styles from './styles.css' with { type: 'css' };

This has been available in bundlers for a while, but now it’s part of the language spec, and runtimes have caught up.

Chrome, Edge, Firefox, and Safari all support with { type: 'json' } as of April 2025. Node.js 22+ supports it too.

The type attribute isn’t an optional decoration but a security mechanism.

The runtime validates the MIME type before processing the file. If someone swaps your JSON endpoint for executable code, the import fails instead of running it.

One caveat: JSON modules only expose a default export. The entire JSON object comes in as default. No named exports.

If you’re importing JSON configs, fixtures, or static data, drop the fs.readFileSync / require() and use this.

TypeScript supports the syntax in 5.3+.

Other Good To Know Features

Three more features made it into the spec.

They’re niche enough that most developers won’t use them directly, but worth knowing they exist:

• Error.isError(): returns true if the value is an Error, even across realms. If you’ve ever had instanceof Error return false because the error came from a different iframe or Node.js vm context, this fixes it.

• Regex pattern modifiers ((?i:HELLO)): toggle flags like i, m, s for specific parts of a regex instead of the whole pattern. Handy when one section of your regex needs case-insensitive matching but the rest doesn’t.

• Duplicate named capture groups: you can now reuse the same group name in different regex alternatives: /(?<id>\d+)|(?<id>[a-f]+)/v. Previously, this was a syntax error, even though only one alternative can match at a time.

📌 TL;DR

• Set methods replace the utility functions you’ve been copy-pasting for years/

• Promise.withResolvers() externalizes resolve/reject, so no more dangling let declarations when bridging callbacks to promises.

• Iterator helpers process data lazily without spreading into arrays first.

• RegExp.escape() safely escapes user input for dynamic regex patterns. Small API, eliminates a whole class of bugs.

• using / await using auto-cleans resources (file handles, DB connections) when they go out of scope. The biggest quality-of-life feature in the spec.

• Promise.try() wraps any function (sync or async) and guarantees a Promise back with errors caught.

• Import attributes (with { type: 'json' }) are now Baseline across all browsers and Node.js 22+.

• Float16Array is the only niche one. ML/graphics use cases only.

• Minimum setup: TypeScript 5.6+, Node.js 22+. Most features are Baseline in browsers already.

Follow me on LinkedIn | Twitter(X) | Threads

Thank you for supporting this newsletter.

Consider sharing this post with your friends and get rewards.

You are the best! 🙏

Share

Press the Like button if you found this post helpful

Your project structure shouldn’t scream “Express” or “Fastify”. It should scream what the app does.

We explored this principle in Screaming Architecture & Colocation.

Vertical Slice Architecture takes it to its logical conclusion: each use case gets its own folder containing everything: handler, validation, types, tests. There is no jumping between 5 directories to understand one operation.

• Share this post & I’ll send you some rewards for the referrals.

The Problem with Layered Structure

You’ve seen this layout a thousand times:

src/
├── controllers/
│   ├── orderController.ts
│   ├── userController.ts
│   └── productController.ts
├── services/
│   ├── orderService.ts
│   ├── userService.ts
│   └── productService.ts
├── models/
│   ├── order.ts
│   ├── user.ts
│   └── product.ts
├── validators/
│   ├── orderValidator.ts
│   └── userValidator.ts
└── tests/
    ├── orderController.test.ts
    └── orderService.test.ts

Want to understand how “create order” works? Open 5 folders.

Want to add a new feature? Touch 5 directories.

Want to delete a feature? Good luck finding all the pieces.

The layered structure is organized by technical concern. It answers “where are all my controllers?” but not “where is the order creation feature?”.

Low cohesion. High cognitive overhead. Every change is a scavenger hunt.

The tax you pay to run multiple agents. Cline Kanban - Sponsor

If you’ve spent any time with coding agents, you know the feeling. You start the morning with a clean plan. Spin up a few agents. One is refactoring the auth module. Another is writing tests. A third is scaffolding a new API endpoint. You’re flying.

Then, around 10:30 AM, you look up and realize you have 20 terminal windows open. One agent is blocked waiting for a decision you forgot to make. Another finished 40 minutes ago, and you never noticed. A third went sideways three commits back. You’re no longer flying. You’re drowning.

You’ve shifted from human as driver to human as director. When running coding agents in parallel, the bottleneck isn’t just context. It’s your own attention trying to manage 10 agents across 10 terminals. You’re losing your mind to terminal chaos.

Meet Cline Kanban, a CLI-agnostic visual orchestration layer that makes multi-agent workflows usable across providers. Multiple agents, one UI. It’s the air traffic controller for the agents you’re already running, regardless of where they live.

• Interoperable: Claude Code and Codex compatible, with more coming soon.

• Full Visibility: Confidently run multiple agents and work through your backlog faster.

• Smart Triage: See which agents are blocked or in review and jump in to unblock them.

• Chain Tasks: Set dependencies so Agent B won’t start until Agent A is complete.

• Familiar UI: Everything in a single Kanban view.

Stop tracking agents and start directing them. Get a meaningful edge with the beta release.

Install Cline Kanban Today: npm i -g cline

Get Started Today

What Is Vertical Slice Architecture?

Vertical Slice Architecture, popularized by Jimmy Bogard, flips the axis of organization.

Instead of grouping by layer, you group by use case.

If you read the screaming architecture post, you might be thinking: “Didn’t we already do this?”. Well, not quite.

Screaming architecture organized by domain module — patients/, orders/, but it still used layers within each module (controller, service, repository).

Vertical slices go further. Each folder is a single use case, not a domain module. create-order and cancel-order are separate slices, not methods on an OrderService.

Core principle:

maximize cohesion within a slice, minimize coupling between slices.

Each slice is one operation, fully self-contained. Adding a new feature means adding a new folder, not modifying shared structures across the codebase.

Here’s the same app, restructured:

src/
├── features/
│   ├── create-order/
│   │   ├── handler.ts
│   │   ├── create-order.ts
│   │   ├── validation.ts
│   │   ├── types.ts
│   │   └── create-order.test.ts
│   ├── cancel-order/
│   │   ├── handler.ts
│   │   ├── cancel-order.ts
│   │   ├── validation.ts
│   │   ├── types.ts
│   │   └── cancel-order.test.ts
│   ├── get-user-profile/
│   │   ├── handler.ts
│   │   ├── types.ts
│   │   └── get-user-profile.test.ts
│   └── list-products/
│       ├── handler.ts
│       ├── types.ts
│       └── list-products.test.ts
└── shared/
    ├── db.ts
    ├── auth.ts
    └── errors.ts

Everything you need to understand “create order” is in one place. Everything you need to delete is in one folder.

Anatomy of a Slice

Let’s build a real slice. Here’s “create order” in Express with Zod validation.

A slice typically has two layers: the handler (HTTP concerns) and the use case (business logic). They live in the same folder — not in separate controllers/ and services/ directories across the project. The types.ts and validation.ts files are standard Zod schemas and TypeScript interfaces — nothing surprising. The interesting part is the split between use case and handler.

features/create-order/create-order.ts — the use case. Pure business logic, no Express types.

import { CreateOrderInput, CreateOrderResult } from "./types";
import { db } from "../../shared/db";

export async function createOrder(
  input: CreateOrderInput,
): Promise<CreateOrderResult> {
  const products = await db.products.findMany({
    where: { id: { in: input.items.map((i) => i.productId) } },
  });

  // some business logic here, ex: calculations, etc.

  const order = await db.orders.create({...});

  return { ... };
}

features/create-order/handler.ts — the HTTP layer. Parses the request, calls the use case, and sends the response.

import { Request, Response } from "express";
import { createOrderSchema } from "./validation";
import { createOrder } from "./create-order";

export async function createOrderHandler(
  req: Request,
  res: Response,
): Promise<void> {
  const input = createOrderSchema.parse(req.body);
  const result = await createOrder(input);
  res.status(201).json(result);
}

Three lines. Parse, execute, respond. If the handler grows beyond this, something is leaking across layers.

The split isn’t a ceremony; it’s practical. The use case function takes typed input and returns typed output. You can unit-test business logic without touching Request or Response.

Note: You’ll notice create-order.ts imports db directly from shared/. If you need test isolation without hitting the database, pass db as a parameter instead. We’ve covered the dependency injection pattern in a previous post: here.

Wiring Slices Together

Slices need to connect to routes. Here’s a simple composition root:

// src/app.ts
import express from "express";
import { createOrderHandler } from "./features/create-order/handler";
import { cancelOrderHandler } from "./features/cancel-order/handler";
import { getUserProfileHandler } from "./features/get-user-profile/handler";
import { listProductsHandler } from "./features/list-products/handler";

const app = express();
app.use(express.json());

// Routes — flat and explicit
app.post("/api/orders", createOrderHandler);
app.post("/api/orders/:id/cancel", cancelOrderHandler);
app.get("/api/users/:id/profile", getUserProfileHandler);
app.get("/api/products", listProductsHandler);

export default app;

Cross-Cutting Concerns

Auth, logging, error handling — where do they live? Exactly where they’ve always lived: the middleware.

// Scope middleware to groups
app.use("/api/orders", authMiddleware, ordersRouter);
app.use("/api/products", listProductsHandler); // public

// Global error handler
app.use(errorHandler);

Slices don’t need to know about authentication. The middleware layer handles it.

Errors inside a slice? createOrderSchema.parse() throws a ZodError, which bubbles up to Express’s error middleware and becomes a 400. Business errors work the same way. The idea is simple: slices throw, middleware translates.

For cross-cutting business concerns like audit logging, event publishing, those belong in shared/ as utilities that a slice calls explicitly. Each order slice calls auditLog.record() directly. A few extra lines, but it’s visible. No hidden magic.

Shared Logic Between Slices

What happens when two slices need the same business rule?

Extract it to shared/:

src/
├── features/
│   ├── create-order/
│   └── cancel-order/
└── shared/
    ├── db.ts
    ├── pricing.ts      ← shared pricing logic
    └── errors.ts

The rule: slices import from shared/. Slices never import from other slices. Enforce this with eslint-plugin-boundaries or Nx module boundaries. We covered the tooling in Screaming Architecture & Colocation. Structure without enforcement is just a suggestion.

This keeps each slice independent. If you delete “cancel order”, nothing else breaks. If you need to change pricing logic, it’s in one place — shared/pricing.ts — not scattered across multiple slices.

Keep shared/ small. The moment it grows into a mini-framework, you’ve recreated the layered architecture inside a different folder.

But when do you extract vs. duplicate?

Simple rule of thumb: if two slices need the same logic and that logic would need to change in sync (same business rule, same source of truth), extract it to shared/. If two slices happen to look similar but could diverge independently, let them duplicate. Premature extraction creates coupling. Duplication between independent slices is cheap.

Data Access

The DB client (db.ts) lives in shared/. But each slice owns its queries: create-order writes its own db.orders.create(), list-products writes its own db.products.findMany(). You can see exactly what data a use case touches by reading one file.

For transactions that span multiple tables, keep them in the slice that orchestrates the operation. The slice that creates an order and writes order items can wrap both in a single db.$transaction() call. If a transaction truly spans multiple use cases, that’s a sign you might need a new slice that represents the combined operation.

When Slices Need to Talk

What happens when creating an order that needs to trigger a notification?

Two options: domain events (create-order emits OrderCreated, other slices subscribe via a lightweight emitter in shared/) or a shared orchestrator (a workflow function in shared/ that calls use cases in sequence). Either way, slices don’t import each other’s internals. They communicate through shared/ infrastructure.

Tradeoffs

This architecture is not a silver bullet. As with everything in programming, it has pros and cons.

What you gain:

• Features are self-contained — easy to find, easy to understand, easy to delete

• Adding features = adding folders, not modifying existing files

• Tests live next to the code they test

• New team members can orient quickly (”find the feature folder, everything’s there”)

• Merge conflicts drop dramatically when teams work on separate features

What you trade:

• Some duplication between slices (mitigated by shared/)

• No single view of “all validation” or “all database queries” across the app

• Requires discipline to keep slices independent (the temptation to import from other slices is real)

• Unfamiliar to developers coming from traditional MVC backgrounds

The duplication tradeoff is the most common objection.

But here’s the thing: a little duplication between independent slices is far easier to manage than tight coupling between shared layers.

When you change shared validation logic, you need to verify that it doesn’t break 15 other features. When you change validation inside a single slice, the blast radius is exactly one feature.

When to Use (and When Not To)

Use vertical slices when:

• Your app has many distinct features or use cases

• Multiple developers or teams work on separate features

• You’re building an API with 15+ endpoints

• You want features that are easy to add and easy to remove

Keep the simpler structure when:

• Your app has fewer than 10 routes

• You’re building a library, not an application

• Heavy cross-cutting logic dominates (e.g., every request does the same 10 processing steps)

• You’re prototyping and the domain isn’t clear yet

📌 TL;DR

• Vertical Slice Architecture organizes code by use case, not by technical layer — one folder per operation, not per concern

• Each slice contains its handler, business logic, validation, types, and tests — everything in one place

• The split between handler (HTTP) and use case (business logic) keeps slices testable without framework dependencies

• Slices import from shared/ but never from each other — enforce this with linting rules

• Keep shared/ small: extract only when two slices share logic that must change in sync. Otherwise, let them duplicate

• Cross-cutting concerns (auth, errors) stay in middleware. Cross-cutting business logic goes in shared/ as explicit calls

• Migrate incrementally: one use case at a time. Old layers shrink naturally until you delete them

• Best suited for apps with many distinct features, multiple teams, or 15+ endpoints. Skip it for small apps or early prototypes

Next Steps

Some of you may not like the idea of grouping all the files related to a feature in a single folder.

However, there’s a lot of value in grouping by features in general. And you don’t need to restructure everything at once.

We covered the broader migration strategy in Screaming Architecture & Colocation. The VSA version is very similar - pick one use case and extract, create the feature folder, inline the service layer, move the tests, do the routing, and repeat.

Start with something isolated. Once the pattern clicks, the rest goes faster.

Thanks for reading, and stay awesome!

Follow me on LinkedIn | Twitter(X) | Threads

Thank you for supporting this newsletter.

Consider sharing this post with your friends and get rewards.

You are the best! 🙏

Share

Press the Like button if you found this post helpful

• Share this post & I’ll send you some rewards for the referrals.

In the Java/C# world, DI containers are a religion.

In Node.js, most developers just import modules directly, until testing becomes a nightmare and swapping implementations means rewriting half the app.

You don’t need dependency injection containers like InversifyJS or tsyringe.

Here’s how to do dependency injection with plain TypeScript, and why it’ll make your code instantly more testable.

Dependency Injection vs. Dependency Inversion

These terms get used interchangeably. But they're not the same.

Dependency Injection (DI) is a technique: instead of a class/function creating its own dependencies, you pass them in from the outside.

Dependency Inversion is a principle (the “D” in SOLID): high-level modules shouldn’t depend on low-level modules. Both should depend on abstractions.

Dependency Injection is how you implement Dependency Inversion.

But you can do DI without inverting anything. This is the place where most Node.js developers stop.

// Direct dependency — no injection
import { db } from './database';

export async function getUser(id: string) {
  return db.query('SELECT * FROM users WHERE id = $1', [id]);
}

This works. But you can’t test getUser without a real database.

You can’t swap PostgreSQL for an in-memory store.

And if database.ts has side effects on import, every test file that touches getUser pays that cost.

The Node.js Anti-Pattern: Import Everything Directly

Here’s what most Express apps look like:

// userService.ts
import { knex } from ‘../lib/database’;
import { sendEmail } from ‘../lib/email’;
import { logger } from ‘../lib/logger’;

export async function createUser(data: CreateUserInput) {
  const [user] = await knex(’users’).insert(data).returning(’*’);
  await sendEmail(user.email, ‘Welcome!’);
  logger.info(`User created: ${user.id}`);
  return user;
}

There are three hardcoded dependencies. And to test this function, you need:

• A running database (or mock Knex globally)

• An email service (or mock the module)

• A logger (or suppress output)

Module mocking (jest.mock, vi.mock) is the usual escape hatch, but it’s brittle because we’re mocking import paths, not the actual contracts.

For example, if you rename a file, your mocks break silently.

Module mocking is a code smell.

It tells you your code has hidden dependencies that should be explicit.

What Dependency Injection Actually Solves

Before we continue further, let’s be clear about what we’re fixing:

• Testability. When a module imports its dependencies directly, you’re forced into module-level mocking (jest.mock(), vi.mock()) to test it. These mocks are fragile, magical, and break when you rename a file. With DI, you pass plain objects, and no mocking framework is needed.

• Swappability. Imagine you have to switch from Knex to Drizzle, or from SendGrid to AWS SES. When dependencies are injected, you swap the implementation in one place. When they’re imported, you touch every file.

• Explicit dependencies. A function’s signature should tell you what it needs. If createUser secretly depends on a database, an email client, and a logger, but its signature only shows data: CreateUserDTO, that’s a lie. DI makes dependencies visible.

• Separation of concerns. Your business logic shouldn’t know (or care) whether it’s talking to Postgres or SQLite, SendGrid or a local SMTP server. DI enforces that boundary naturally.

Now, let’s see how to do dependency injection in Node.js without any frameworks.

Step 1: Constructor Injection (Manual DI)

The simplest fix: accept dependencies as parameters.

// userService.ts
interface UserRepository {
  create(data: CreateUserInput): Promise<User>;
}

interface EmailService {
  send(to: string, subject: string): Promise<void>;
}

interface Logger {
  info(message: string): void;
}

export function createUserService(
  repo: UserRepository,
  email: EmailService,
  logger: Logger
) {
  return {
    async createUser(data: CreateUserInput) {
      const user = await repo.create(data);
      await email.send(user.email, ‘Welcome!’);
      logger.info(`User created: ${user.id}`);
      return user;
    },
  };
}

Before and After DI: How You Use the Code

The real difference isn’t just how the service is defined, but how it’s consumed.

Before DI, we use direct imports (hidden dependencies):

// Somewhere in your route handler or controller
import { createUser } from ‘./userService’;

// Just call it. What does it need? Who knows.
// Knex? Email service? Logger? You can’t tell from here.
const user = await createUser({ email: ‘alice@example.com’, name: ‘Alice’ });

Dependencies are invisible.

The function looks simple, but it’s secretly reaching into the module graph for a database client, an email service, and a logger.

You only discover this when something breaks or when you try to test it.

After DI, we use Factory + DI (explicit dependencies):

// In your composition root or setup code
import { createUserService } from ‘./userService’;
import { createUserRepo } from ‘./repos/userRepo’;
import { createEmailService } from ‘./infra/email’;
import { createLogger } from ‘./infra/logger’;

// Dependencies are explicit at creation time
const userService = createUserService(
  createUserRepo(knex),
  createEmailService({ apiKey: process.env.SENDGRID_KEY! }),
  createLogger({ level: ‘info’ })
);

// Now use it — the service is fully configured
const user = await userService.createUser({ email: ‘alice@example.com’, name: ‘Alice’ });

Yes, the setup is more verbose. But now you can see every dependency. The function signature tells the truth.

When you read the composition root, you know exactly what each service needs, no grepping through imports, no surprises.

Step 2: The Composition Root

If every service takes its dependencies as arguments, where do you actually wire everything together?

At the composition root, the entry point of your application. This is the one place that knows about all the concrete implementations.

// composition-root.ts
import Knex from ‘knex’;
import { createKnexDatabase } from ‘./infra/knexDatabase’;
import { createUserService } from ‘./services/userService’;
import { createOrderService } from ‘./services/orderService’;
import { createEmailService } from ‘./infra/email’;
import { createLogger } from ‘./infra/logger’;

export function createApp() {
  // Infrastructure
  const knex = Knex({
    client: ‘pg’,
    connection: process.env.DATABASE_URL,
  });
  const db = createKnexDatabase(knex);
  const email = createEmailService({ apiKey: process.env.SENDGRID_KEY! });
  const logger = createLogger({ level: ‘info’ });

  // Repositories
  const userRepo = createUserRepo(db);
  const orderRepo = createOrderRepo(db);

  // Services
  const userService = createUserService(userRepo, email, logger);
  const orderService = createOrderService(orderRepo, userService, logger);

  return { userService, orderService, knex };
}

// server.ts
import express from ‘express’;
import { createApp } from ‘./composition-root’;

const app = express();
const { userService, orderService } = createApp();

app.post(’/users’, async (req, res) => {
  const user = await userService.createUser(req.body);
  res.status(201).json(user);
});

Everything flows downward from one place. No global singletons. No magical auto-wiring. Just functions calling functions.

When to Reach for a Container?

Manual DI works beautifully for small-to-medium apps.

But when you have 20-30+ services with complex dependency graphs, the composition root becomes hard to read and follow.

I’ve personally used tsyringe. It’s a lightweight container, easy to use and configure.

tsyringe uses decorators and reflect-metadata to inspect constructor parameters and auto-wire dependencies.

It supports singleton, transient, and scoped lifecycles, with strong TypeScript support.

To be honest, I didn’t have any trouble with it.

Here is a simple example:

import ‘reflect-metadata’;
import { container, injectable, inject, singleton } from ‘tsyringe’;
import Knex from ‘knex’;

@singleton()
class KnexDatabase implements Database {
  private knex = Knex({ client: ‘pg’, connection: process.env.DATABASE_URL });

  users = {
    create: async (data: CreateUserInput) => {
      const [user] = await this.knex(’users’).insert(data).returning(’*’);
      return user;
    },
    findById: async (id: string) => {
      return this.knex(’users’).where({ id }).first() ?? null;
    },
  };
}

container.register(’Database’, { useClass: KnexDatabase });

@injectable()
class UserService {
  constructor(@inject(’Database’) private db: Database) {}

  async createUser(data: CreateUserInput) {
    return this.db.users.create(data);
  }
}

// Resolve with all dependencies auto-wired
const userService = container.resolve(UserService);

If you’re not sure whether you need a container, start simple without an additional framework.

You can easily add it later if needed.

The Testing Payoff

Here’s why all this matters. Let’s compare full test files side by side.

Before: Testing with Module Mocking

import { describe, it, expect, vi, beforeEach } from ‘vitest’;

// Mock every dependency by file path — get any path wrong and it silently breaks
vi.mock(’../lib/database’, () => ({
  knex: vi.fn().mockReturnValue({
    insert: vi.fn().mockReturnValue({
      returning: vi.fn().mockResolvedValue([{ id: ‘1’, email: ‘test@example.com’ }]),
    }),
  }),
}));

vi.mock(’../lib/email’, () => ({
  sendEmail: vi.fn(),
}));

vi.mock(’../lib/logger’, () => ({
  logger: {
    info: vi.fn(),
  },
}));

// Now import the function AFTER the mocks (order matters!)
import { createUser } from ‘./userService’;
import { knex } from ‘../lib/database’;
import { sendEmail } from ‘../lib/email’;

describe(’createUser’, () => {
  beforeEach(() => {
    vi.clearAllMocks();
  });

  it(’creates a user and sends a welcome email’, async () => {
    const user = await createUser({ email: ‘test@example.com’, name: ‘Test’ });

    expect(user.id).toBe(’1’);
    expect(sendEmail).toHaveBeenCalledWith(’test@example.com’, ‘Welcome!’);
  });
});

Problems everywhere:

• Path-coupled: rename ../lib/database to ../db/database and the mock breaks silently — the test passes but uses the real module

• Import order matters: vi.mock calls are hoisted, but if you get it wrong, debugging is miserable

• Type-unsafe: you’re casting to any because the mock system doesn’t know your interfaces

• Framework-locked: switch from Vitest to Node’s built-in test runner? Rewrite every mock

After: Testing with DI

import { describe, it, expect } from ‘vitest’;
import { createUserService } from ‘./userService’;

describe(’createUser’, () => {
  it(’creates a user and sends a welcome email’, async () => {
    // Plain objects that satisfy the interface — no mock framework needed
    const fakeRepo = {
      create: async (data: any) => ({ id: ‘1’, email: data.email }),
    };
    const fakeEmail = {
      send: async () => {},
    };
    const fakeLogger = {
      info: () => {},
    };

    // Track calls manually if needed (or use vi.fn() — your choice, not a requirement)
    const emailCalls: any[] = [];
    fakeEmail.send = async (to: string, subject: string) => {
      emailCalls.push({ to, subject });
    };

    const service = createUserService(fakeRepo, fakeEmail, fakeLogger);
    const user = await service.createUser({ email: ‘test@example.com’, name: ‘Test’ });

    expect(user.id).toBe(’1’);
    expect(emailCalls).toEqual([{ to: ‘test@example.com’, subject: ‘Welcome!’ }]);
  });

  it(’logs user creation’, async () => {
    const logs: string[] = [];
    const service = createUserService(
      { create: async (data: any) => ({ id: ‘42’, email: data.email }) },
      { send: async () => {} },
      { info: (msg: string) => logs.push(msg) }
    );

    await service.createUser({ email: ‘test@example.com’, name: ‘Test’ });

    expect(logs).toEqual([’User created: 42’]);
  });
});

The difference:

• No mocking framework required: plain objects that match the interface

• Type-safe: TypeScript checks your fakes against the real interfaces

• No import order tricks: just functions and objects

• Portable: works with Vitest, Jest, Node’s test runner, or even a plain script

• Each test is self-contained: no shared mutable mock state leaks between tests

📌 Key Takeaways

1. Dependency Injection isn’t a framework feature — it’s passing arguments to functions. You already know how to do it.

2. Module mocking is a smell. If you need vi.mock() to test something, remember that something has hidden dependencies.

3. Start with manual DI. Factory functions + a composition root covers 90% of Node.js apps.

4. Graduate to a container (tsyringe) when your dependency graph gets complex. Not because it’s “proper”, but because it saves maintenance.

5. The real value is testability. DI makes unit testing trivial, integration testing focused, and your architecture honest about its dependencies.

Follow me on LinkedIn | Twitter(X) | Threads

Thank you for supporting this newsletter.

Consider sharing this post with your friends and get rewards.

You are the best! 🙏

Share

Press the Like button if you found this post helpful

• Share this post & I’ll send you some rewards for the referrals.

Open most Node.js projects, and you see this:

src/
├── controllers/
├── services/
├── models/
├── middleware/
├── utils/
└── routes/

What does this app do?

You see that it’s an Express app. But that’s all the structure tells you.

Is it an e-commerce platform? A healthcare system? A social network?

You’d have to open files and read code to find out.

That’s the problem.

What Is Screaming Architecture?

Uncle Bob coined the term:

Your project structure should scream what the application does, not what framework it uses.

For example, a healthcare app should look like this:

src/
├── patients/
├── appointments/
├── prescriptions/
├── billing/
└── shared/

You open the folder and immediately know: this is a healthcare system.

The domain is front and center.

Express, REST, GraphQL, Prisma, React, those are implementation details, tucked inside each feature.

And this is not just about aesthetics.

When folders map to business capabilities, you get:

• Discoverability: New developers find code faster.

• Ownership: Teams own features, not layers.

• Change isolation: Modifying “appointments” doesn’t require touching 5 different layer folders.

• Deletion: You can remove an entire feature by deleting one folder.

• Low/High Coupling: Low coupling between features and High coupling for a single feature.

Or we could also look at it in another way to see more clearly how a single feature maps across different technical layers:

The Colocation Principle

In the React world, we must strive to:

Keep things as close as possible to where they're used.

Consider the following hierarchy:

1. If only one component uses it → put it in that component’s file

2. If only components in one folder use it → put it in that folder

3. If multiple folders use it → move it up to the nearest shared parent

4. If the whole app uses it → put it in shared/ or lib/

This is the same idea as screaming architecture, applied at a granular level.

Don't prematurely extract.

Don't create utils/ and helpers/ folders that become junk drawers.

Combining Both: Feature-First Structure

Here’s what a feature-first Node.js project looks like when you combine screaming architecture with colocation:

src/
├── patients/
│   ├── patient.controller.ts
│   ├── patient.service.ts
│   ├── patient.repository.ts
│   ├── patient.types.ts
│   ├── patient.validation.ts
│   ├── patient.routes.ts
│   └── __tests__/
│       ├── patient.service.test.ts
│       └── patient.controller.test.ts
├── appointments/
│   ├── appointment.controller.ts
│   ├── appointment.service.ts
│   ├── appointment.repository.ts
│   ├── appointment.types.ts
│   ├── appointment.validation.ts
│   ├── appointment.routes.ts
│   └── __tests__/
│       └── appointment.service.test.ts
├── shared/
│   ├── middleware/
│   │   ├── auth.middleware.ts
│   │   └── error-handler.ts
│   ├── database/
│   │   └── prisma.ts
│   └── types/
│       └── common.ts
├── app.ts
└── server.ts

Every feature is self-contained.

Tests live next to the code they test.

Shared infrastructure sits in shared/, but only things that are genuinely shared across features.

The Same Principle in React

src/
├── features/
│   ├── patients/
│   │   ├── PatientList.tsx
│   │   ├── PatientDetail.tsx
│   │   ├── usePatients.ts
│   │   ├── patient.types.ts
│   │   └── patient.api.ts
│   ├── appointments/
│   │   ├── AppointmentCalendar.tsx
│   │   ├── BookAppointment.tsx
│   │   ├── useAppointments.ts
│   │   └── appointment.api.ts
├── shared/
│   ├── components/
│   │   ├── Button.tsx
│   │   └── Modal.tsx
│   ├── hooks/
│   │   └── useAuth.ts
│   └── lib/
│       └── api-client.ts
├── App.tsx
└── main.tsx

Same idea.

Features own their components, hooks, types, and API calls.

shared/ contains only genuinely reusable pieces.

When Layers Still Make Sense

Layers aren’t always wrong. They work when:

• Your app is small (< 10 files). Feature folders are overhead for a simple CRUD API.

• You’re building a library. Internal structure matters less than the public API.

• Your team is one person. You already know where everything is.

The pragmatic hybrid: features at the top level, layers within each feature.

Each feature has its own controller, service, repository, but they’re colocated, not scattered.

Enforcing Boundaries

Structure without enforcement is just a suggestion.

Here's how to make it stick:

ESLint (with eslint-plugin-boundaries)

// .eslintrc.js
module.exports = {
  plugins: ['boundaries'],
  settings: {
    'boundaries/elements': [
      { type: 'patients', pattern: 'src/patients/*' },
      { type: 'appointments', pattern: 'src/appointments/*' },
      { type: 'shared', pattern: 'src/shared/*' },
    ],
  },
  rules: {
    'boundaries/element-types': [2, {
      default: 'disallow',
      rules: [
        { from: 'patients', allow: ['shared'] },
        { from: 'appointments', allow: ['shared', 'patients'] },
      ],
    }],
  },
};

TypeScript Project References

// src/shared/tsconfig.json — every referenced project needs composite: true
{
  "compilerOptions": {
    "composite": true,
    "rootDir": ".",
    "outDir": "../../dist/shared"
  }
}

// src/patients/tsconfig.json
{
  "compilerOptions": {
    "composite": true,
    "rootDir": ".",
    "outDir": "../../dist/patients"
  },
  "references": [
    { "path": "../shared" }
  ]
}

Each feature is a TypeScript project.

It can only reference what's listed in references.

The compiler enforces boundaries at build time.

📌 Key Takeaways

1. Your folder structure is documentation. It should tell a new developer what the app does in 5 seconds.

2. Organize by feature, not by layer. Controllers, services, and models for the same feature belong together.

3. Colocate aggressively. Tests, types, and utilities live next to the code that uses them. Move things to shared/ only when two or more features need them.

4. Migrate incrementally. One feature at a time, one PR at a time. No big-bang restructures.

5. Enforce with tooling. ESLint boundaries, TypeScript project references, or Nx module boundaries. Structure without enforcement decays.

Follow me on LinkedIn | Twitter(X) | Threads

Thank you for supporting this newsletter.

Consider sharing this post with your friends and get rewards.

You are the best! 🙏

Share

Press the Like button if you found this post helpful

Those engineers ship less, talk more, think further ahead, and treat AI like a power tool, not a replacement for judgment.

• Share this post & I’ll send you some rewards for the referrals.

Imagine spending six weeks building a sleek, real-time notification system that nobody actually requested.

You nailed down the “right architecture”, covered the codebase with tests, and perfected the documentation.

Then comes the week before launch. Your PM demos the masterpiece, and suddenly part of your customers refuse to use it while the other asks why a certain bug still exists.

Stories like this project remind me of the difference between being efficient and being effective.

Efficient engineers do things right.

Effective engineers do the right things.

After 8+ years of shipping software, hiring engineers, and watching teams succeed and fail, I’ve distilled what makes engineers genuinely effective into four disciplines.

And none of them is about writing clever code.

BrightData: Connect Your AI To The Internet’s Data - Sponsor

Bright Data’s Web MCP solves web access for LLMs and AI agents, allowing them to effectively search, extract, and navigate the web without getting blocked. It helps to:

• Search the web in real-time

• Extract data from any website

• Navigate and interact with pages

• Bypass blocks and restrictions

It comes with a generous free tier - 5,000 MCP requests every month - for free!

Try For Free

1. Solve the Right Problems; Not Just Any Problem

Traits: Care about the user. Understand team strategy. Prioritize ruthlessly.

The most expensive line of code is the one that solves the wrong problem.

I’ve seen teams spending time into plubming, like managing a custom-built deployment pipeline, instead of leveraging $50/month SaaS.

Here is the uncomfortable part: most engineers aren’t trained to say no.

We’re rewarded for building. Promotions come from shipping. Saying “we shouldn’t build this” doesn’t show up in a pull request.

But caring about users, I mean actually caring, not only claiming that on a performance review, means understanding their real problems deeply enough to know which solutions are worth pursuing and which are engineering vanity projects.

And you can’t make that judgment in a vacuum.

You need to understand your team’s strategy:

• What are we trying to accomplish this quarter?

• How does my work connect to revenue, retention, or reliability?

Engineers who can answer those questions prioritize themselves.

Engineers who can’t are always waiting to be told what to do next.

So next time, before writing any line of code, force yourself through these three questions:

• Who suffers if this doesn’t ship? If the answer is “nobody, really,” put it in the icebox.

• What’s the cheapest version that tests the hypothesis? A spreadsheet, a Figma prototype, or a hardcoded endpoint can often answer the question a six-week feature build was supposed to answer.

• What am I not doing by doing this? Opportunity cost is invisible until you’ve missed a deadline on the thing that actually mattered.

Of course, we can’t do some of these things by ourselves. That’s why we have Product Managers who are the point of contact to the end users and our organization.

Our job as Effective Engineers is to advocate for users, do extensive user research, and prioritize user needs.

2. Keep It Simple; Leave It Better

Traits: Simplicity over cleverness. Quality as a discipline. The Boy Scout Rule.

I’ve reviewed pull requests where the author used three levels of abstraction to avoid repeating four lines of code.

The DRY principle is good. But taken to its extreme, it produces code that’s “elegant” but unreadable to everyone except the person who wrote it, and often to them too, three months later.

Simplicity isn’t the absence of thought. It’s the result of deep thought.

It means you’ve understood the problem well enough to solve it without over-engineering.

The engineers I respect most write code that a new team member can read on their first day and say, “Okay, I see what this does”.

But simplicity alone isn’t enough.

The effective engineers also leave things better than they found them.

Every PR is an opportunity: fix a flaky test, update a stale README, delete dead code, or rename a confusing variable.

None of these show up in a sprint demo.

All of them compound into a codebase that’s a joy to work with versus one that slowly rots.

So the next time you write and ship code, try to:

• Set a complexity budget. If a solution requires more than one new abstraction, pressure-test whether that abstraction earns its keep. Often it doesn’t.

• Timebox polish. I allocate roughly 10-15% of every feature’s time for cleanup, not gold-plating, but genuine improvement to the code I touched and the code around it.

• Measure quality that matters. Track things like time-to-first-meaningful-PR-review for new hires, or incident rate per deploy. These tell you more about codebase health than test coverage percentages.

You have to be comfortable with invisible contributions.

The payoff comes in months, not days: fewer incidents, faster onboarding, less time debugging code nobody understands.

3. Earn Trust; Communicate Relentlessly

Traits: Build trust and social capital. Communicate effectively. Operate with autonomy.

Early in my career, I thought trust was a soft-skills thing, something you got for free by being “nice”.

That’s not how it works.

Trust is an engineering asset.

It’s the reason one engineer can get a risky refactor approved in a single meeting while another spends two sprints writing a design doc that still gets rejected.

Think about it mechanically: engineers who’ve built trust get more autonomy.

More autonomy means they can take bigger swings.

Bigger swings, when they land, build more trust. It compounds like interest.

And the inverse is just as powerful: one blown deadline or one surprise production incident you didn’t communicate about can set you back months of accumulated credibility.

Communication is the engine that drives all of this.

Not “being good at presentations”, I mean the boring, daily discipline of keeping people informed. Status updates nobody asked for. A Slack message before you merge something risky. Flagging a blocker on Day 1 instead of Day 5.

The engineers who do this consistently become the ones everyone wants on their project.

Here are a few things you could try:

• Estimate honestly, then pad 20%. On one project, I started adding explicit “risk buffers” to my estimates, and my on-time delivery rate went from roughly 60% to over 85% in two quarters.

• Communicate bad news early. If a project is slipping, saying so on Day 3 builds trust. Saying so on Day 13 destroys it. I’ve never seen anyone punished for early transparency. I’ve seen plenty punished for late surprises.

• Review others’ code generously. Fast, thoughtful code reviews are one of the highest-leverage trust-building activities in engineering. They signal “I respect your time and your work”. They also build social capital, the kind of relationship equity that means people answer your Slack messages in minutes instead of hours.

• Invest in relationships outside your team. Grab coffee with the infrastructure team. Understand what the data team is struggling with. Cross-team relationships pay dividends when you need a favor, a quick answer, or buy-in on a proposal.

Building trust slowly means you won't be the hero on Day 1. You might watch a louder, faster colleague get more visibility early on. The patience required is real.

And there's an uncomfortable truth: trust is context-dependent.

Switching teams or companies resets the meter. You have to be willing to re-invest every time.

4. Think Long-Term; Adapt Constantly

Traits: Second-order thinking. Comfort with new challenges. Wielding AI as a force multiplier.

Junior engineers think about whether their code works. Mid-level engineers think about whether their code is maintainable. Senior engineers think about what their code causes, downstream, six months from now, in systems they don't own.

And here's the thing that's changed in the last two years:

Long-term thinking now includes your relationship with AI tooling.

The engineers who treat GitHub Copilot, Claude, or Cursor as magic black boxes are building on sand.

The ones who understand what these tools are good at (boilerplate, scaffolding, routine refactors), what they're bad at (nuanced architecture decisions, security edge cases, understanding your specific business context), and how to verify their output, are the engineers who are genuinely 2-3x more productive.

But only because they bring the judgment the AI lacks.

Treat AI-generated code like a pull request from a confident but context-blind junior.

Review every line. Question every assumption. The speed is real, but so are the subtle bugs.

Being comfortable with new challenges has always mattered. Now it's existential.

The landscape shifts every six months.

The engineers who thrive aren't the ones who memorize every new framework.

They're the ones who've built strong enough fundamentals that they can pick up any tool quickly and evaluate it critically.

Second-order thinking is slow.

Learning new tools takes time away from shipping.

There's a real risk of analysis paralysis, and an equally real risk of chasing every new AI tool instead of mastering the one you have.

The discipline is knowing when the blast radius is large enough to warrant the extra thought, and when to just ship.

You can learn a new framework in a weekend.

You can learn a new AI tool in an afternoon.

These four disciplines take years. Start now.

See you next time! 🙌

PS: My friend Marko Denic has recently launched his new FREE e-book: The Technical Decision Framework. It’s about a framework for the choices that shape your codebase.

Follow me on LinkedIn | Twitter(X) | Threads

Thank you for supporting this newsletter.

Consider sharing this post with your friends and get rewards.

You are the best! 🙏

Share

Press the Like button if you found this post helpful

• Share this post & I’ll send you some rewards for the referrals.

Imagine a team launches a new product. Traffic grows. Everything’s fine.

Then one day, a query takes 8 seconds instead of 80ms. Engineers start adding indexes. Caching layers. Read replicas.

None of it helps enough.

The problem wasn't performance. It was bad database design. And by the time they realized it, they had 200 million rows in production and a Slack channel dedicated to database incidents.

Database decisions are long-term bets.

Get them wrong early, and you'll spend years firefighting.

Get them right, and your system scales quietly while you build features.

Your Schema Will Outlive Your Code. Plan Accordingly.

A careless column type. A missing foreign key constraint. An unnecessary denormalization because “it might be faster”.

These choices feel small when you're building v1. But databases are permanent in ways code isn't.

You can refactor a service in a weekend.

A schema migration on a table with 500 million rows in PostgreSQL?

That's a multi-month project involving table locks, replica lag monitoring, and very careful coordination with the ops team, who definitely don't want to hear from you at 2 AM.

The teams that win long-term treat table design with the same respect they give code architecture. Maybe more, because you can't just roll back a schema change when 50 million user records depend on it.

Start With Reality, Not With Tables.

Most engineers rush straight to CREATE TABLE before understanding what they're actually modeling.

Don't do this.

Spend real time mapping the business domain.

What entities exist in the real world? What relationships matter to the business? What constraints does reality enforce that your database should mirror?

If you’re building a job board, understand that a job posting isn’t just a row. It has a lifecycle: draft, published, filled, and expired. It belongs to a company. It attracts applications. Each application connects a candidate to a posting.

The database should enforce what the domain requires.

If your schema allows states that can't exist in reality, eventually someone will put your data into one of those states.

Normalization Is Your Friend (Until It Isn’t)

Normalization means organizing data to eliminate redundancy and dependency issues.

Third normal form (3NF) is the target - every column depends on the primary key, the whole key, and nothing but the key.

In practice, this means that a user's data is in one table, addresses in another, and orders in a third. Then, we join them when needed.

This prevents update anomalies. We change a user’s email once, not in seventeen places. We can also safely delete an order without losing customer data.

But over-normalization can destroy read performance.

If your application shows “user profile with last 10 orders” on every page load, and that requires five joins across normalized tables, you’re paying a cost.

A good rule of thumb is:

Let query patterns guide your final design.

Start normalized.

Denormalize deliberately when you have real performance data.

To mitigate the above-mentioned problem, we might want to add a materialized view that flattens this query and then refresh it on writing.

Or we can do something else, depending on the business case and needs.

Denormalization is a tool. Use it when the tradeoff is clear.

Indexes: The Contract You Make With Future You

An index is a data structure that makes lookups fast by avoiding full table scans.

Without an index on users.email, a query like WHERE email = 'user@example.com' checks every row. With an index, it jumps directly to the match.

But indexes aren’t free.

Every index slows down writes. The database must update the index on every INSERT, UPDATE, or DELETE. Indexes consume disk space. And poorly chosen indexes bloat over time, requiring maintenance.

The strategy I follow:

• Index foreign keys and columns used in WHERE, JOIN, and ORDER BY clauses

• Avoid indexing columns with low cardinality (e.g., boolean flags)

• Use composite indexes when queries filter on multiple columns together

• Monitor and rebuild indexes periodically to prevent fragmentation

Hint: Use pg_stat_user_indexes to monitor index usage in PostgreSQL.

Index deliberately.

Measure the impact using EPLAIN ANALYZE.

Remove what doesn't serve you.

Constraints Are The Best Documentation You’ll Ever Write

Foreign keys. NOT NULL. UNIQUE. CHECK constraints.

These aren’t optional guardrails. They’re how you encode business rules into the database itself.

A foreign key constraint ensures referential integrity. If orders.user_id references users.id, you can’t have an orphaned order pointing to a deleted user.

A NOT NULL constraint guarantees a value exists. No defensive null checks in application code.

A CHECK constraint validates data at write time. Age must be positive. Status must be one of five valid values.

This matters because constraints catch bugs before they corrupt data.

Constraints add minor write overhead, maybe 1-2%, or sometimes less. But they give you guaranteed correctness.

If your database allows invalid data, eventually you’ll have invalid data.

Performance Is A Design Choice, Not a Tuning Exercise

I’ve seen teams spend weeks chasing query plans, adding caches, and tuning connection pools.

Most of the time, the real problem is the schema.

A single redesign could fix the issue forever: moving a frequently-joined column into the main table, splitting a bloated table into hot and cold storage, adding a covering index, and partitioning by time range.

Here's what makes database design genuinely hard: you don't know the full business context at the start. Requirements evolve. Query patterns change.

The answer isn’t perfection upfront. It’s about designing for change.

Keep things simple. Use clear naming conventions. Avoid premature optimization. And critically, don't be afraid to migrate the schema when you learn something new about your domain or your access patterns.

A well-designed schema can handle 10x growth with minor adjustments. A poorly designed one requires rewrites.

What I Wish Someone Had Told Me

If I could give my younger self advice, I'd say this:

Practice designing schemas for real systems. Pick LinkedIn, Twitter, or Airbnb. Map the entities. Draw the relationships. Think through the queries. Do it on paper before you touch a database.

Learn SQL deeply. Not just SELECT and JOIN. Window functions. CTEs. Query plans. Execution order. Understand what the database does with your query.

Start simple, but extensible. Don't build for scale you don't have. But leave room to grow. Design your schema so that adding columns or splitting tables doesn't require a full rewrite.

Measure everything. You can't optimize what you don't measure. Track query times. Index usage. Table sizes. Slow query logs.

The best engineers I know treat database design like architecture. They think through the consequences of their decisions. They plan for failure modes. They build systems that last, not just systems that work.

And they're never ashamed to run a migration when they learn something new.

Because databases don't forget your mistakes, but they do forgive your improvements.

Follow me on LinkedIn | Twitter(X) | Threads

Thank you for supporting this newsletter.

Consider sharing this post with your friends and get rewards.

You are the best! 🙏

Share

If you enjoy The T-Shaped Dev, it would mean the world to me if you invited friends to subscribe and read with us. If you refer friends, you will receive benefits that give you special access to The T-Shaped Dev.

How to participate

1. Share The T-Shaped Dev. When you use the referral link below, or the “Share” button on any post, you'll get credit for any new subscribers. Simply send the link in a text, email, or share it on social media with friends.

Refer a friend

2. Earn benefits. When more friends use your referral link to subscribe (free or paid), you’ll receive special benefits.

• Get Pull Request Checklist for 1 referrals

• Get Brag List (Work Log) Template for 2 referrals

• Get Technical Design Document Template for 3 referrals

Refer just 3 people & I'll send you some rewards. 🎁

Refer a friend

Imagine you’re using one AI tool for everything - designing, planning, coding, reviewing, etc.

After a while, you start to see some pitfalls in the LLMs output.

While many LLMs are doing okay for general-purpose tasks, they tend to fall short when it comes to highly specialized tasks.

That’s why it is important to use different types of AI agents, each optimized for a different task.

For example, let’s say you have a UI problem. You would ask for help from the Front-End guy, not the Back-End guy, even though the Back-End guy has some knowledge of the front-end too.

We should apply the same logic and approach to using LLMs as well.

Use the right agent for the right task so we can craft better software.

In the previous article, we covered the systematic AI code review workflow: Plan, Generate, Validate.

Now, let’s map the right tools to each phase:

• Plan → use Advisors (think through decisions)

• Generate → use Generators (write code fast)

• Validate → use Reviewers (catch issues automatically)

Each phase needs a different type of AI agent. Let’s understand what makes each one specialized and what traps to avoid when using.

The Three Types of AI Agents

Each AI agent is trained and optimized for specific tasks.

Using a generator for security review is like using a hammer to tighten a screw.

It’s technically possible, but we would use the wrong tool for the job.

Here is the breakdown:

• Advisors (Claude, ChatGPT)

  • Purpose: understanding and decision making

  • Optimized for: explaining concepts, evaluating trade-offs, designing, researching, refactoring strategy

  • Blind to: your specific codebase, real-time feedback, automated integration

• Generators (Cursor, Copilot)

  • Purpose: fast code implementation

  • Optimized for: speed, autocomplete, pattern matching

  • Blind to: security vulnerabilities, architectural implications, edge cases

• Reviewers (CodeRabbit and similar)

  • Purpose: quality assurance and bug detection

  • Optimized for: security, bugs, performance, consistency

  • Blind to: design decisions, why code exists, future requirements

If you’re wondering when to use each, use these questions to navigate your judgment:

• Need to make a design decision? → use Advisor

• Need to write code fast? → use Generator

• Need to validate code quality? → use Reviewer

Your role is to select the tool, knowing which agent to use and when.
You have to validate, reason, and do problem-solving.

Now, let’s dig deeper into each AI agent.

Note: Some IDEs, like Cursor, have different modes built in, like Agent, Plan, Debug, Ask, so you could use one IDE, switch the mode, and have a different type of AI agent. However, you still have to know how to use each of those tools.

The Advisor: When Decisions Matter

Advisors don’t write your code or review it automatically.

They help you think through problems, break down complex tasks into an executable plan, understand trade-offs, and make better decisions before you start implementing a specific approach.

Advisors excel at explaining the “why” behind code, not just what it does, but the reasoning and trade-offs that led to that implementation.

✅ With Advisors, you should prefer:

• Using before making major architectural decisions

• Understanding existing and/or unfamiliar code

• Exploring different approaches and strategies and their trade-offs

• Providing context about your project, current choices, and structure

• Learning new patterns and concepts

⛔ With Advisors, you should avoid:

• Writing code (generators are faster)

• Using them for bug detection (reviewers are better)

• Expecting it to know your codebase or internal team’s dynamics

• Following advice blindly without understanding

So,

Advisors help you make better decisions.

Use them before you start coding, not after.

The Generator: When Speed Matters

The Generators excel at writing code quickly.

They’re autocomplete on steroids, trained on millions of code examples to predict what you’re trying to write.

✅ With Generators, you should prefer:

• Using for daily coding, boilerplate, CRUD operations, etc

• Scaffolding tests

• Writing type definitions and interfaces

• Writing code to follow existing patterns and conventions

• Iterating on suggestions and do not always accept the first try

⛔ With Generators, you should avoid:

• Trusting it for security-critical code without review

• Assuming it validates business logic

• Assuming it writes proper type definitions of your domain models

• Using it to make architectural decisions

• Skipping review because “AI wrote it”

So,

Generators are for speed.
Always validate the output with a review and your reasoning.

Use them after you have a concrete plan in mind.

The Reviewer: When Quality Matters

Reviewers are specialized for finding issues in existing code.

An example of a Reviewer is CodeRabbit.

They don’t generate. They analyze, detect patterns and conventions, and flag problems.

✅ With Reviewers like CodeRabbit, you should prefer:

• Using on every PR before merging

• Addressing security and bug findings immediately

• Using suggestions as learning opportunities (you could ask Advisors to help)

• Configuring rules and guidelines for your specific tech stack and codebase

⛔ With Reviewers like CodeRabbit, you should avoid:

• Skipping review because the code “looks fine”

• Dismissing warnings or applying suggestions without understanding them

• Using it to write new code (wrong tool)

• Expecting it to validate business logic

So,

Reviewers help us catch things which generators miss.

They act as our QA and Security guy.

Use them while or after you generate code. Then you fix and repeat.

Now that we understand each agent’s specialty.

Here is how to use them together effectively:

• Making a decision? → Advisor (understand trade-offs first, make a plan)

• Writing code? → Generator (fast implementation)

• Code written? → Reviewer (catch issues automatically)

• Issues found? → Generator (quick fixes) → Reviewer (validate)

And remember:

⚠️ Your role is to select the tool and always validate and understand the output!

When Agents Disagree

Sometimes, different agents might suggest conflicting approaches.

Here is how I resolve them:

• For architecture, I weigh the Advisor’s opinion carefully, but also consider the current context, business needs, and constraints.

• For implementation details, I follow the generated code from the Generator because it knows the codebase best and the already established patterns.

• For security issues, I trust the Reviewer’s suggestions (like CodeRabbit) because security is non-negotiable.

In the end, the final decision is yours because you know all the specific domain and business context, needs, and constraints.

AI shouldn’t be your excuse for making wrong and unjustified decisions.

You are the Software Engineer who navigates and drives the AI, not the other way around.

You’re the final decision maker!

📌 TL;DR

• Using one AI tool for everything means missing what other specialized tools catch.

• Prefer to use a different AI agent, each optimized for different tasks

• We have generally three types of AI agents: advisors (Claude/ChatGPT), generators (Cursor/Copilot), and reviewers (CodeRabbit).

• Match the tool to the tasks, advisors for decisions, generators for speed, reviewers for safety.

So try out these three agent types in your daily coding workflow and let me know how you found them.

I promise this way of working will improve your code.

Hope this was helpful.

See you next time! 🙌

👋 Let’s connect

You can find me on LinkedIn, Twitter(X), Bluesky, or Threads.

I share daily practical tips to level up your skills and become a better engineer.

Thank you for being a great supporter, reader, and for your help in growing to 29.5K+ subscribers this week 🙏

Once upon a time, a developer spent an afternoon building a user registration API with AI assistance.

API endpoints, proper validation, clean error handling—everything compiled perfectly and worked flawlessly in staging.

The PR was approved and merged into production.

Hours later, the security team sent an urgent Slack message.

The newly introduced endpoint was vulnerable to SQL injection through unvalidated query parameters.

One line of code. One blind spot.

One security vulnerability that an automated review would have caught instantly.

That’s the current reality of AI and Vibe coding without a systematic workflow:

It’s not a productivity, it’s a technical debt at AI speed.

To mitigate this, we need a new system to handle the massive code generation facilitated by AI.

In today’s article, I’ll share a systematic AI code review workflow to adapt to the new AI and Vibe coding era.

Why You Need a Loop

Most developers follow this pattern:

1. Generate code with AI

2. Push to production

3. Hope for the best

The problem with this approach is that AI optimizes for “working”, not “correct” code.

It writes code that compiles and runs, but might have security vulnerabilities, performance issues, edge case failures, and inconsistent error handling.

Imagine the following scenario: You ask your LLM to generate an Express API endpoint for user registration. The code works perfectly:

app.post(’/api/register’, async (req, res) => {
  const { email, password, username } = req.body;
  
  const user = await db.query(
    `INSERT INTO users (email, password, username) VALUES (’${email}’, ‘${password}’, ‘${username}’) RETURNING *`
  );
  
  res.json({ success: true, user });
});

However, there are a few major problems. SQL injection vulnerability. No password hashing. No input validation. No error handling, etc. You get the point.

The main point is that the code “works”, but it’s a security nightmare.

This is where the three-phase loop comes in:

Plan → Generate → Review → Ship
         ↑            ↓
         └── Fix ─────┘

The key principle is:

Separate generation from validation.

You might use:

• Generation AI, like Cursor, Claude, or Copilot, optimizes for speed and functionality.

• Review AI, like CodeRabbit, optimizes for security, performance, and quality.

• You act as an orchestrator of both.

This way, each phase catches different types of issues.

Let’s dive in.

Phase 1: Plan Before You Generate

Good AI output starts with good input.

Planning before you generate any code creates better results.

Why planning matters:

• clear specs = better AI output

• prevents “works but unmaintainable” code

• creates a checklist for validation

• saves hours of debugging later

You might use Cursor Plan mode, or any other LLM like Claude or ChatGPT, to come up with a detailed action plan.

I personally try to fill out the following template before moving to the code generation:

Feature: [Name]
Purpose: [One sentence]
Inputs: [List with types and validation rules]
Outputs: [Success and error cases]
Edge cases: [What could go wrong?]
Security considerations: [What must be protected?]

Feel free to edit it based on your current context, problem, and task.

This approach helps me be more confident that I’ve outlined all the important requirements and considerations before moving to the next phase.

If we follow the example from above related to the user registration endpoint for an Express API, we might prompt the following:

I need a user registration endpoint for an Express API. Users provide email, password, and username. Help me design the endpoint that handles validation errors, duplicate emails, and weak passwords. What else should I consider for security, validation, and error handling?

Based on the given output, summarize the findings into the above-mentioned template, so you can share it in the prompt in a structured format when starting to generate code.

Phase 2: Generate With Context

Once you’ve gone through the planning and have a structured and summarized plan, you’re ready to generate.

Since you already defined a plan, you can create focused and high-quality prompts.

Generation best practices:

• Generate one endpoint, component, or feature at a time. Don’t generate the entire service. The smaller and more focused the task, the better the outcome.

• Use separate prompts/chats per task. Maintain the context window. Keep it as small as possible. This also reduces the costs.

• Copy relevant sections from your plan directly into the prompt.

• Iterate 2-3 times rather than expecting perfection on the first try.

• Specify your exact tech stack, code style, and structure. Provide examples from the codebase if relevant.

AI generation is a conversation, not a one-shot command!

During the code generation phase, you want to manually check:

• Does it follow your tech stack conventions?

• Are the types and interfaces correct?

• Does it match your project structure?

• Are dependencies the ones you actually use?

If something looks off, create a new chat and refine your prompt with more specific guidance.

In the LLM world, if the first prompt is not okay, it’s hard to change it later.
Better create a new chat with a clean context and an improved prompt.

Coming back to the example from above related to the user registration endpoint for an Express API, we might prompt the following:

Create an Express TypeScript POST endpoint at /api/register for user registration.

Requirements:
- Accept email (string), password (string), username (string) in request body
- Validate email format (RFC 5322)
- Validate password: minimum 8 characters with at least one number
- Validate username: 3-20 alphanumeric characters only
- Hash password with bcrypt (12 rounds) before storing
- Use parameterized database queries to prevent SQL injection
- Handle duplicate email (return 409 with generic message)
- Handle validation errors (return 400 with field-specific errors)
- Handle database errors gracefully
- Return 201 with user object (exclude password) on success

Use Zod for input validation and proper TypeScript types throughout.

Even though we’ve outlined a detailed plan and have a solid code, we might still miss important stuff.

For example, “Are there any missed edge cases?”, “Performance implications?”, “Is the validation comprehensive enough?”, etc.

This is exactly why we need the review phase.

We want to get a higher confidence in what we ship and double-check that we haven’t missed important considerations.

Phase 3: Review and Validate

We have a working code. Now, it’s time to validate it with a second AI perspective specialized for review.

Why bother reviewing AI-generated code?

• AI generators have blind spots. They optimize for “working”, not “correct” code.

• Different AI models catch different issues and blind spots.

• Automated reviews find problems in seconds.

• Ensures consistency across your codebase.

An example of such an AI code review tool is CodeRabbit.

What CodeRabbit catches:

• Security: SQL injections, XSS vulnerabilities, exposed secrets, etc.

• Bugs: race conditions, incorrect error handling, etc.

• Performance: missing db indexes, N+1 queries, etc.

• Best practices: inconsistent error handling, missing type safety, etc.

Put simply, CodeRabbit complements human reviewers, adding a lot of context based on your repo and general engineering practices.

📌 TL;DR

This systematic AI code review workflow isn’t optional; it’s how you maintain quality at AI speed:

• Plan before you generate (upfront thinking saves hours).

• Generate with context (good prompts = good code).

• Review with specialized AI (e.g., CodeRabbit catches what generators miss).

Hope this was helpful.

See you next time! 🙌

P.S. If you’re into Web Development, I recommend you subscribe to Marko Denic’s newsletter, which is full of many tips and tricks.

👋 Let’s connect

You can find me on LinkedIn, Twitter(X), Bluesky, or Threads.

I share daily practical tips to level up your skills and become a better engineer.

Thank you for being a great supporter, reader, and for your help in growing to 29.3K+ subscribers this week 🙏

A while ago, I worked for a client who had a diverse portfolio of digital products.

They’ve struggled to develop new features, reuse business logic and functionality across products, and also scale the engineering team.

By digging deeper into the case, I’ve found they have:

• bad architecture, which doesn’t support their growth

• years of accumulated technical debt

The root cause turned out to be a 2-Tier Architecture that had outlived its purpose.

In today’s article, I’ll share how I tackled this challenge by migrating their system from a Two-Tier Architecture to a Three-Tier Architecture, introducing a scalable, robust GraphQL API.

IcePanel is a collaborative diagramming and modelling tool for designing software architecture. Create interactive, layered views for different stakeholders from a single source of truth.

Try for free

Before we dive into the actual migration journey, let’s ensure we understand what a 2-Tier and a 3-Tier architecture are.

What is Two-Tier Architecture?

2-Tier Architecture is a simple setup in which your application talks directly to a database.

You have a presentation layer (the front-end) and a data layer (the database).

That’s it. No middle layer.

Think of it like a simple website or app that sends requests directly to the database, retrieves the data, and displays it to users.

What is Three-Tier Architecture?

3-Tier Architecture adds an essential middle layer between your front-end and database. Now you have:

1. Presentation Layer - the front-end (what users see).

2. Business Logic Layer - the API (where the magic happens).

3. Data Layer - the database (where data lives).

The middle layer handles all the business logic, security, and data processing.

The main difference between a 2-Tier and a 3-Tier architecture is the separation of concerns.

In a Two-Tier architecture, your front-end must know too much about your data, whereas in a Three-Tier architecture, the business logic layer acts as a smart middleman.

This smart middleman protects your data and enables the whole system to be more flexible.

The Starting Architecture (Two-Tier)

Now, let me show you what the client’s system looked like before the migration.

They had three main services, all sharing one MySQL database:

• Portal - The customer-facing web portal. The front-end was React, but the back-end was built with CakePHP 2 (an outdated PHP framework).

• Admin - The internal management web portal of the company. Everyone in the company used it to run the business, from operations to finance. Also built with CakePHP 2.

• API - A small REST API with just three methods for customers. Again, Cake PHP 2.

All three services are connected directly to the same MySQL database.

The database was the integration point for everything.

This setup created several serious problems.

The Top Technical Challenges

• Duplicated logic - The same business logic and rules were duplicated in multiple services.

• Database as an integration point - Having multiple services write to the same database is risky. There is no single source of truth for business logic and data validation. Also, it is very hard to update or migrate the database when having multiple clients.

• Technical debt - CakePHP 2 reached end of life. There was a need to modernize the tech stack by using well-adapted technologies.

• Hard to scale the engineering team - This was hard to find developers to work on front-end and back-end with the present technologies. There was a need to enable full-stack developers.

• Slow feature development - With the challenges mentioned above, feature development was slow, hindering the business's growth.

To address these challenges, we introduced a new middle layer—a GraphQL API.

The Final Architecture (Three-Tier)

The GraphQL API became the heart of the system.

It sits between all front-ends and the database.

The Main Architectural Improvements

The new architecture solved our major pain points:

• Centralized business logic - All business-related logic lives in one place now. The GraphQL API is the single source of truth for all features.

• Single database owner - Only the GraphQL API can access the database. This makes the system safer and easier to refactor.

• Modern tech stack - We built the API using Node.js, a technology already used by the company. Apart from that, GraphQL provides flexible, efficient data fetching to accommodate the needs of different API clients.

• Full-stack friendly - Having the same core technology, JavaScript, on the front-end and back-end, enabled the company to hire Full-Stack JavaScript developers.

• Ready for microservices - To ensure the system's future flexibility and the company’s growth, the API was designed as a Modular Monolith, so that, when needed, internal modules could be extracted into separate services.

The Migration Approach

We didn’t rebuild everything overnight.

This was too risky from both a business and an engineering perspective.

The business must continue operating while the groundwork is being done under the hood.

That’s why we took an iterative approach:

• Phase 1: Build the GraphQL API - We created the new API layer, starting with the most critical business logic, shared across multiple services.

• Phase 2: Migrate Portal - The Portal front-end started using the GraphQL API. We moved features one by one and tested thoroughly.

• Phase 3: Update Admin - We upgraded Admin to a modern version of CakePHP. Then we gradually moved its logic to the GraphQL API, starting with shared functionality.

• Phase 4: Rewrite REST API - The customer-facing REST API had only three methods, so we rewrote it in Node.js to align with the new stack.

• Phase 5: Migrate Admin to React - We started migrating the Admin to React, instead of CakePHP, prioritizing newly incoming feature requests.

📌 TL;DR

• 2-Tier Architecture is when multiple clients or services directly communicate with the Database.

• 3-Tier Architecture is when multiple clients or services communicate with a middle layer, usually an API, which then communicates with the actual DB.

• Having three clients communicating with a DB means duplicated business logic everywhere.

• Having a middle layer, in this case a GraphQL API, means a single user communicates with the DB, removing duplicate business logic.

• Centralizing business logic in the GraphQL API eliminated duplicate code, made onboarding new teammates easier, enabled quicker feature delivery, and created a system ready to scale into microservices when needed.

Hope this was helpful.

See you next time! 🙌

👋 Let’s connect

You can find me on LinkedIn, Twitter(X), Bluesky, or Threads.

I share daily practical tips to level up your skills and become a better engineer.

Thank you for being a great supporter, reader, and for your help in growing to 28.7K+ subscribers this week 🙏

You’ve tried everything you can think of, but the issue persists…

Debugging doesn’t have to be this painful.

It’s a skill you can develop with the right strategies and tools.

It’s something you can learn and get better at.

Mastering debugging can save you time, energy, frustrations, and money as well as improve your code quality.

In today’s article, I’ll share ten practical debugging techniques I use daily that have saved me countless hours.

I’ll also show you some modern tools that could make these strategies even more effective.

Being effective while debugging is crucial.

It’s really important to get it right so you find the root cause of the issue, fix it asap, and then make your customers happy.

Over the years, as a Software Engineer, I’ve found that good debugging is not only about the processes and systems you employ, but also about your mindset and tooling.

I’ve played around with various tools both at my daily job and side projects.

Recently, I tried out Multiplayer, a new session replay platform that captures both the front-end and back-end traces.

I believe we can make debugging much simpler with the help of Multiplayer, effective, and easier to do.

Part 1: Set Yourself Up For Success

1. Reproduce the Error Consistently

You can’t fix what you can’t see.

The foundation of effective debugging is consistently reproducing the bug.

Start by writing step-by-step instructions that make the bug appear every time.

For example, map out how a user request flows through the whole system, so you build a clear mental model.

This is especially useful in the context of microservice architecture, where a single user request might hit several services.

Finding the bug in the ground schema is hard if you don’t have a good understanding of the flow.

Nowadays, there are tools that record session replays, so you can leverage them to see the flow from the front-end to the back-end instead of doing it manually.

An example of such a tool is Multiplayer, which captures full-stack session recordings.

2. Reproduce the Error Quickly

Once you know how to reproduce a bug, make it fast.

Configure your development environment to jump straight to the problematic area.

This helps to quickly test various hypotheses and solutions.

Every second you save between reproducing the bug and testing a fix compounds over the course of dozens of debugging iterations.

3. Capture the Full Context

Debugging an issue in a complex system —from front-end to back-end —is hard.

It requires acquiring as much information and context as needed.

Imagine a user reporting a problem—“the page crashed”—but you miss information like why they clicked, what data they had loaded, or the system's state.

So, before digging into the problem, try to collect as much context as possible—ask your product manager, write an email to a client, check recordings, logs, etc.

You might also consider using a tool like Multiplayer, which silently captures user sessions so you can collect all the context related to a single issue.

Part 2: Active Debugging Techniques

4. Isolate the Problem

Large codebases make finding bugs like finding a needle in a haystack.

You need to narrow down the scope quickly.

Use a binary search approach: divide your code into working and non-working parts.

Comment out half of the suspicious code. Does the bug occur? If yes, the problem is in the other half. If no, it’s in the code you commented out.

You might also use breakpoints like a binary search to quickly jump to different points in your code.

Repeat this process until you’ve nailed the problematic area.

The main goal is to minimize the scope from “somewhere in this 1000-line file” to “somewhere in these 20 lines”.

5. Use Your Debugger

Debuggers are invaluable tools that provide real-time insights into your program’s execution.

You can set breakpoints, inspect variables, step through the code line by line, and examine the call stack.

The main benefit is that you can easily see the exact flow of your program and spot anomalies as they happen.

If you’re using tools for recording session replays, you could bring those recordings directly into your IDE.

I’ve personally tried Multiplayer and it worked like a charm.

6. Rubber Duck It

Rubber duck debugging is simple but extremely powerful.

The main idea is that you explain your code line by line to an object (🦆), a colleague, or even yourself.

You describe what you expect to happen at each step.

The act of explaining forces you to slow down and verify your assumptions.

There is a big difference in how we think about the code when we read and when we speak loudly about it.

I’ve caught the bug many times in the middle of the explanation.

7. Form And Test Hypotheses

To achieve good results while debugging, you must adopt a more scientific, methodological approach and avoid any random changes.

Do the following

• Form a hypothesis about the root cause (ex, “I think the API is returning null when the user has no preferences…”).

• Experiment to verify it (add logging, set breakpoints, etc).

• Observe the result (confirm or reject the hypothesis).

• Fix the code based on what you learned.

• Verify the fix actually solves the problem.

• Repeat the cycle again with a new hypothesis if needed.

This systematic approach prevents you from going in circles and helps you build an understanding of your codebase.

Part 3: When You’re Stuck

8. Document Your Progress

When a bug is particularly hard, write down what you’ve tried.

Keep a running list of your experiments, hypothesis, and their results.

This prevents you from doing the same thing twice and expecting different results.

Documentation also makes it easier for others to help you.

You can easily ping a colleague, share your progress, and learnings so far.

You might also consider a tool like Multiplayer to annotate session replays with sketches and comments.

9. Take Strategic Breaks

This might sound counterintuitive, but stepping away from your laptop is sometimes the fastest way to solve a bug.

Taking a 15-minute walk allows your mind to rest and your subconscious to process the problem.

I can’t count how many times the solution to a difficult bug popped into my head while taking a walk, being at the toilet, or just making a drink.

There’s something about disengaging from the problem that allows your brain to make new connections.

10. Leverage AI Smartly

AI coding tools can be powerful debugging partners, especially if you give them the right information.

The right context is the key.

Try providing as much information about the bug as possible to your AI IDE and see how it could reason about it.

Of course, it’s not always correct, but you can quickly test and verify certain hypotheses.

Then, you could focus on the ones your AI coding tool hasn’t thought about.

It’s also helpful if you could share screenshots or session recordings to provide context.

I’ve personally tried Multiplayer’s integration.

I’ve used it to feed my AI assistant with a full-stack session recording, so it can see the full context of a problem.

After that, I wrote specific prompts and dug deeper into the problem.

AI is not a magic solution, but it’s a valuable debugging partner when given complete information.

Multiplayer provides Full Stack Session Recordings.

Here’s how it helps with debugging and fixing bugs:

• Capture full-stack session recordings.

• Annotate your replays with sketches and comments.

• Bring full-stack session recordings directly into your IDE.

• Give your AI coding tools all the context they need.

Access 1-month Free Trial

📌 TL;DR

• Reproduce the error consistently.

• Set up your environment to quickly reproduce the bug.

• Capture the full context and information.

• Isolate the problem.

• Use your debugger.

• Rubber duck the problem.

• Form and test hypotheses.

• Document your progress.

• Take strategic breaks.

• Leverage AI smartly.

Hope this was helpful.

See you next time!

Today’s action step: Take a look at your debugging process and see how you can apply at least one of the mentioned techniques.

👋 Let’s connect

You can find me on LinkedIn, Twitter(X), Bluesky, or Threads.

I share daily practical tips to level up your skills and become a better engineer.

Thank you for being a great supporter, reader, and for your help in growing to 28.5K+ subscribers this week 🙏

In Node.js, error handling relies on try-catch blocks and exceptions.

While this is a common way in Node.js apps, it creates an unpredictable control flow and hidden failure points.

A few years ago, I discovered the Result Pattern approach for handling errors, and it completely changed the way I look at error handling in Node.js applications.

The Result Pattern approach makes errors explicit, type-safe, and part of your function signatures.

In today’s article, I’ll dig deeper into the error handling and how to use the Result Pattern to better manage it.

Problems With Using Exceptions For Flow Control

Most Node.js applications rely on exceptions for error handling.

You throw errors when something goes wrong, and catch them somewhere up the call stack.

This favors the so-called fail-fast principle because you terminate the method execution immediately once you throw an exception.

With this approach, you make the caller responsible for handling the exception.

The problem is that the client of the method must know which exceptions to handle, which is not obvious from the method’s signature.

This makes exceptions invisible and creates an opportunity for bugs related to improper error handling of these exceptions.

Code becomes unpredictable since you’re not sure if the method throws an exception or not.

Here is a simplified example of creating an order:

Use Exceptions For Exceptional Situations

A good rule of thumb is to use exceptions for unexpected errors and exceptional situations.

You basically have two types of errors:

• Errors you know how to handle

• Errors you don’t know how to handle

You can use exceptions for the errors you don’t know how to handle. And you should catch and handle them at the lowest level possible.

For the errors you know how to handle, you could use the Result Pattern and handle the errors in a more functional way.

Make these types of errors explicit since you already know about them.

This way is more explicit and clearly shows that the method can fail.

The drawback is that the caller of the method has to check whether the operation succeeded or failed.

Using The Result Pattern For Better Error-Handling

The Result Pattern makes errors explicit and type-safe.

Instead of throwing exceptions, methods return a Result object that contains the success data or error information.

You can think of the Result as a container that holds one of two things:

• Success: Your data is inside.

• Error (or Failure): Information about what went wrong.

The key change here is that errors become values, not exceptions.

You can handle them like any other data in your program.

Here is an example of what the Result object might look like:

Applying the Result Pattern

Now that we have the IResult interface and utility methods, we could refactor the above-mentioned example by switching from using exceptions to the Result Pattern.

You can notice a few things as improvements:

• No more throwing exceptions.

• The return type of the method is explicit - using the IResult return type.

• It is clear what errors the method can return.

Another advantage of using the Result Pattern is that it simplifies the testing. It’s much easier to mock the Result object than to throw and handle exceptions.

As we said earlier, one drawback of the Result Pattern is its verbosity, as it might introduce more code compared to exceptions.

📌 TL;DR

• Exceptions are for exceptional situations.

• Use exceptions for errors you don’t know how to handle.

• Use the Result Pattern for errors you know how to handle, making the error handling more explicit and obvious.

• The Result Pattern allows you to handle errors more elegantly in a functional way, express the intent that the method could fail, and encapsulate the error inside.

So try out the Result Pattern and let me know how you found it.

I promise it will improve your code.

Hope this was helpful.

See you next time!

👋 Let’s connect

You can find me on LinkedIn, Twitter(X), Bluesky, or Threads.

I share daily practical tips to level up your skills and become a better engineer.

Thank you for being a great supporter, reader, and for your help in growing to 28K+ subscribers this week 🙏

You’re changing your current environment, including your teammates, office, and so on.

You’re also not sure how it would impact your career.

So yes, it’s a bit nerve-racking.

Till now, I’ve changed more than four tech companies, ranging from startups to big tech unicorns.

I’ve seen different onboarding plans and ways to kick off your “first impression” in your new workplace.

One of the biggest lessons I’ve learned for myself is:

Don’t rely on your company’s onboarding plan. Create one for yourself!

Regardless of the company's size and seasonality, there are many flaws.

It’s hard to create the “complete” plan for every new joiner.

That’s why it’s crucial to take ownership of your onboarding plan.

The effort you put in now will pay dividends for months.

A strong start makes you appear to be someone who cares.

This sense of ownership shows professionalism.

In today’s article, I’ll share ten lessons I’ve learned in my career on how to successfully onboard in your new company.

I also shared and applied these lessons with all the people I managed to onboard as an Onboarding Buddy.

I saw the work, so that’s why I’m sharing these lessons with you.

Before Day 1: Set Yourself Up For Success

If you have a long notice period, reach out to your future manager or team before you start.

Ask what you can do to prepare before your first working day.

When I did that at my last company, they sent me a Udemy course on microservices architecture - a core part of their tech stack.

On Day 1, I showed up already speaking “their language”.

This shows two things: you actually prepare and you signal you are proactive.

Also, start a work log or brag document from Day 1.

Write down what you’re working on, problems you solved, your wins, and impact.

This becomes invaluable for 1:1s, performance reviews, and promotion discussions.

You can read more about it here:

Week 1-4: Learn Fast, Contribute Faster

Ship Code Early

I truly believe in getting your hands dirty immediately.

Aim to ship something in the first week, even in the first few days.

You might fix a bug, add a small feature, improve something in the codebase, or even add a formatting or linting rule.

I’ve worked in both frontend and backend, so when I joined my last company, I looked for bugs I could fix in both areas.

In my first week, I managed to raise the bar high by making an impact by starting to deliver.

During my first retro, the team said like I’d been there for months, not days.

There’s usually a “capacity penalty” when someone new joins.

You reduce this penalty by contributing quickly.

Another tip here is to:

Maintain your focus while exploring the codebase.

Don’t try to understand the entire codebase from the beginning.

Pick one area and start from there.

Start Reviewing Code Immediately

You might not understand the business domain yet, but you can still add value.

You can still share tips and tricks on code reviews related to software design, architecture, and engineering practices, like readability, testing, etc.

This shows that you care.

You also build your credibility as an expert in a particular field.

As you learn more about the product, you can begin to question requirements and suggest more effective approaches.

Ask Questions; Ask Even More

Your questions reveal what you care about. Ask good ones!

For example:

• How do we make money?

• How do we handle payments?

• What are our team’s responsibilities?

• etc.

Ask your buddy, your mentor, your team, or people outside your team.

And try not to eat lunch alone.

I’m an introvert, so this was hard for me.

However, I tried to eat at least twice a week with people outside my team.

This way, I met more smart people, heard different perspectives, and learned about challenges across the company.

Align on Expectations

On your 1:1s with your manager, sit down and clarify your goals:

• What does success look like in my first month?

• What about the next three months?

• How to progress further in the career ladder?

Get specific.

Vague goals lead to vague results.

A good starting point is to create your 30-60-90 plan in a document.

This document maps out a new hire’s expectations from the perspective of the onboarding Team within the first 90 days of his new role.

🎁 Notion Template: Work Log (aka Brag List) Template For Software Engineers

Use this template to create your own work log (brag list) and list of accomplishments.

I want this!

Paid subscribers, you can get it here:

I want this FREE!

Month 2-3: Build Your Network and Increase Impact

Map The Organization

This is especially helpful for Senior+ roles.

The main idea here is to get to know the different teams, their responsibilities, and their core domains.

Since you’re new to the company, you have the perfect excuse to message someone from this team and ask what they’re working on:

“Hi, I’m new here, and I heard about your team lately. I’d love to learn what you work on and how our teams might interact…”

This is incredibly easy as a new person, and gets much harder later. Use this window.

Understand The Business, Not Just The Code

Learning the tech stack is one challenge.

Understanding the business and product domain is another.

The best engineers combine technical knowledge with business context.

If you don’t understand the product well, you can’t build the right solution.

If the product doesn’t work, the code doesn’t matter.

Talk to product managers and more experienced engineers.

Try to understand the business.

And try to work on high-impact things.

This isn’t always possible—sometimes you have to fix boring bugs—but communicate with your manager about your impact.

Use Your Fresh Perspective

You see things that others have become blind to.

Something that doesn’t make sense to you probably doesn’t make sense at all.

Others just got used to it.

When you spot something that could be improved, document it.
Better yet, fix it yourself if you can.

Seek opportunities to make a positive impact.

Apply your fresh perspectives not only to the code, but also to the current processes, including onboarding.

Accept The Entropy

Accept that many things won’t make sense at first, especially if you’re going from a small to → big company.

This is completely normal.

Give it time. It gets clearer.

📌 TL;DR

• Reach out to your manager before you start. Ask for materials to prepare.

• Start your brag document from day 1.

• Contribute code in week 1.

• Start code reviews immediately.

• Ask questions.

• Try to eat lunch with people from different teams.

• Align on goals with your manager.

• Map important teams.

• Learn the business, not just the code.

• Apply your fresh perspective.

Hope this was helpful.

See you next time!

👋 Let’s connect

You can find me on LinkedIn, Twitter(X), Bluesky, or Threads.

I share daily practical tips to level up your skills and become a better engineer.

Thank you for being a great supporter, reader, and for your help in growing to 28K+ subscribers this week 🙏

Some time ago, I had an interview, which I almost failed.

The interviewer asked me questions like Promises and Event Loop.

I knew what they were, but I failed to clearly elaborate and explain them.

If you can’t explain it simply, do you understand it really well?

After the interview, I understood that some knowledge was missing.

I decided to dig deeper into JavaScript and fill my understanding and knowledge gaps.

I read many books and articles and took many notes along the way.

Every time I have a JavaScript interview, I review my notes to refresh my knowledge and prepare.

In today’s article, I’ll delve deeper into asynchronous programming in JavaScript, covering Promises, Async/Await, and the Event Loop.

This is part 4 of the “Ace Your Next JavaScript Interview” series.

If you missed the previous articles, see the bottom of this post.

Let’s dive in!

CodeRabbit: Free AI Code Reviews in CLI - Sponsor

CodeRabbit CLI is an AI code review tool that runs directly in your terminal. It provides intelligent code analysis, catches issues early, and integrates seamlessly with AI coding agents like Claude Code, Codex CLI, Cursor CLI, and Gemini to ensure your code is production-ready before it ships.

• Enables pre-commit reviews of both staged and unstaged changes, creating a multi-layered review process.

• Fits into existing Git workflows. Review uncommitted changes, staged files, specific commits, or entire branches without disrupting your current development process.

• Reviews specific files, directories, uncommitted changes, staged changes, or entire commits based on your needs.

• Supports programming languages including JavaScript, TypeScript, and more.

• Offers free AI code reviews with rate limits so developers can experience senior-level reviews at no cost.

• Flags hallucinations, code smells, security issues, and performance problems.

• Supports guidelines for other AI generators, AST Grep rules, and path-based instructions.

Get Started Today

Promises

A Promise is an object that allows us to take action when a future event happens.

It’s a placeholder for a value that will be available at some point in the future.

Imagine ordering food at a restaurant—you get a receipt (Promise) that represents your order, even though your meal is not ready yet.

Promises have three possible states:

• pending - the operation is still in progress

• fulfilled - the operation completed successfully

• rejected - the operation failed

Upon creation, the Promise takes a function that will be passed two arguments - a resolution callback and a rejection callback.

Most of the time, you’ll be consuming Promises rather than creating them.

The then() method is available on the Promise object and will run with the value passed to the resolve() function.

The catch() method runs if the reject() function was called.

One of the most powerful features of Promises is chaining.

If a then() handler returns another Promise, you can chain additional then() calls.

Async/Await

While Promises are powerful, the syntax can become hard to read and follow with complex chains.

The async/await keywords provide a syntax sugar over the Promises that will make your code read as if it were synchronous.

There are a few key points about async/await:

• You can only use await inside functions marked with async.

• Async functions always return a Promise.

• Use try/catch blocks for error handling instead of .catch().

• The code executed asynchronously despite looking synchronous.

Event Loop

Here is where things get really interesting.

JavaScript is single-threaded, meaning it can only do one thing at a time.

So how does it handle asynchronous operations without blocking the entire program?

The answer is its execution flow, which is based on an event loop.

On a high level, the engine runs an endless loop that checks if there are tasks waiting for it in a queue.

If there are, it executes them and continues to wait for more.

Any code that can’t run immediately is queued, and the execution continues until it exhausts the call stack.

setTimeout(() => {
  console.log('Later');
}, 1000);

console.log('Now');

// Output:
// Now
// Later (after 1 second)

Even with a zero timeout, the callback still runs after the synchronous code:

setTimeout(() => {
  console.log('Later');
}, 0);

console.log('Now');

// Output:
// Now
// Later (after 1 second)

The Event Loop manages two main areas:

• Call Stack - where your currently executing code lives.

• Task Queue - where asynchronous callbacks wait to be executed.

The Event Loop only processes the task queue when the call stack is empty.

setTimeout(() => {
  console.log('Later');
}, 0);

// This loop keeps the call stack busy
for (let i = 0; i < 100000; i++) {
  console.log(i);
}

// Output:
// 0
// 1
// 2
// ...
// 99999
// Later

The loop keeps adding items to the call stack and the event loop never gets a chance to reach the task queue.

When asynchronous calls are queued using the same method, for example, setTimeout, their execution order follows the order in which they were added.

setTimeout(() => {
  console.log('Later');
}, 0);

setTimeout(() => {
  console.log('Even Later');
}, 0)

// Output:
// Later
// Even Later

But if we queue a Promise and a call to setTimeout, the Promise will be the first to run.

setTimeout(() => {
  console.log('Later');
}, 0);

Promise.resolve().then(() => {
  console.log('Also Later');
});

// Output:
// Also Later
// Later

This is because promises and timeouts are put on two separate queues that have different priorities:

• Macrotask Queue (aka task queue) - setTimeout, setInterval, DOM events, etc.

• Microtask Queue (aka jobs queue) - Promise callbacks, queueMicrotask(), etc.

The event loop prioritizes the execution of pending microtasks.

Then the event loop will handle the next pending macrotask.

Immediately after every macrotask runs, the event loop will run all pending microtasks before continuing with the macrotasks again.

Here is a nice visualization I found on the Internet:

Let’s see one final code example to check your understanding:

console.log("start");

setTimeout(() => console.log("timeout"), 0);

Promise.resolve().then(() => console.log("Promise.resolve"));

new Promise((resolve, reject) => {
    resolve();
    console.log("executor");
}).then(() => console.log("promise"));

console.log("synchronous");

To see the answer, see the comments.

📌 TL;DR

• Promises give you a clean way to handle future values and chain async operations.

• Async/Await is a syntax sugar over Promises, giving you a simple mental model and making your code more readable.

• The Event Loop is a fundamental aspect of async programming in JavaScript.

• Event Loop handles async operations efficiently in JavaScript.

Hope this was helpful.

See you next time!

Ace Your Next JavaScript Interview Series

1. Scope, Hoisting, and Closures

2. Values, References, Coercion, and Equality

3. this, new, Prototypes, and Classes

👋 Let’s connect

You can find me on LinkedIn, Twitter(X), Bluesky, or Threads.

I share daily practical tips to level up your skills and become a better engineer.

Thank you for being a great supporter, reader, and for your help in growing to 27.7K+ subscribers this week 🙏

Over the last few years, I have managed to work with various software architectures, ranging from monoliths to microservices and their variations.

Each architecture had its own set of unique challenges, problems, and advantages.

And there is one architecture that really stood out—the Modular Monolith architecture.

Modular monoliths blend the simplicity and robustness of traditional monolithic applications with the flexibility and scalability of microservices.

I’d say that modular monoliths bring the best of both worlds.

The modular monolith architecture allows you to work in a unified codebase with clearly defined boundaries and independent modules.

This way, you can have high development velocity without the complexity of distributed systems.

In today’s article, I’ll share more about modular monolith architecture and why you should know about it.

CodeRabbit: Free AI Code Reviews in VS Code - Sponsor

CodeRabbit brings real-time, AI-powered code reviews straight into VS Code, Cursor, and Windsurf. It lets you:

• Get contextual feedback on every commit, not just at the PR stage

• Catch bugs, security flaws, and performance issues as you code

• Apply AI-driven suggestions instantly to implement code changes

• Do code reviews in your IDE for free and in your PR for a paid subscription

Install in VS Code for FREE

What is a Modular Monolith?

A modular monolith is a single deployable application that’s internally organized into well-defined and loosely-coupled modules.

The modules are split into logical boundaries, grouping related functionality together.

These modules communicate through well-defined, public APIs, events, or messages, instead of directly calling each other’s functionality.

These approaches promote modularity and separation of concerns, and improve the cohesion of the system.

You can think of modular monoliths as a microservices architecture packaged into one deployment unit.

This way, you get the organizational benefits of the service boundaries without the distributed system overhead.

Even if you want to scale one of the modules due to high traffic or other factors, you can easily extract the module and deploy it independently.

Modular monoliths give you this kind of flexibility.

What is a Modular Architecture?

To design a modular monolith, we must understand what a modular architecture is.

The core principles of modular architecture include:

• Separations of Concerns - Each module is independent, handling a specific business domain or business capability.

• Loose Coupling - Modules depend on interfaces, not implementations.

• High Cohesion - Related functionality stays together within modules.

• Explicit Interfaces - Clear contracts define how modules interact.

This means that each module:

• Must be independent.

• Must provide the required functionality.

• Must expose a well-defined interface to other modules.

The end goal is not to have 100% independent modules because this would mean that modules are not integrated together.

The main idea is to have loosely coupled modules and keep the number of dependencies low.

We can use a few techniques to keep the modules independent, like data isolation and linting rules, for example.

If we see that two modules communicate too much with each other, you might have incorrectly defined boundaries.

Then, you could consider merging the two modules together.

Remember:

A module is a grouping of related functionalities together that are accessed through a well-defined interface.

And once you have a modular architecture, you can easily extract modules into separate services.

Start With a Modular Monolith

In recent years, developers have favored the microservices architecture.

Yes, it provides many benefits like better scalability, clear service boundaries, independence, and much more.

But, it does come with a big cost - complexity.

I’d say that most teams and companies would be better off starting with a monolith application.

As Martin Fowler says:

You shouldn't start a new project with microservices, even if you're sure your application will be big enough to make it worthwhile.

And even better, consider starting with a modular monolith.

When you’re building a new system, you’re making countless architectural decisions with incomplete information.

You don’t fully understand your users patterns, scaling needs, domain boundaries, etc.

Starting with microservices in these early days will lock you into these often incorrect assumptions.

Even big players like Shopify and Google bet on modular monoliths.

You can read this paper from Google about “Towards Modern Development of Cloud Applications”.

In this paper, Goggle identifies five main challenges with microservices:

• Performance - Sending data between services over the network slows everything down, especially when you split your app into too many pieces.

• Correctness - Most big failures happen when different versions of services try to talk to each other and mess up.

• Management - Have to manage multiple different applications, each with its release schedule.

• Frozen APIs - Once you create an API between services, it’s really hard to change it without breaking everything else.

• Development Velocity - When you need to make changes across multiple services, you can’t just deploy them all at once - you have to coordinate carefully.

As you see, the cost of starting with microservices is high.

So starting with a modular monolith sounds compelling.

I also recommend reading about the fallacies of distributed computing if you’re unfamiliar with them.

Remember:

You can easily migrate from a modular monolith architecture to a microservices architecture because each module is well defined, isolated, and separated.

Benefits of a Modular Monolith

Modular monoliths have multiple benefits.

Here are the ones I consider the most important:

• Simplified deployment - You build, test, and deploy one application instead of multiple services across different environments.

• Improved performance - Communication between modules happens through fast in-memory calls, instead of slow network requests.

• Enhanced development velocity - You have a single codebase to manage which simplifies the debugging and the overall development process.

• Easier transaction management - Managing transactions in a distributed systems is very challenging. With modular monoliths you use a single database and transactions are much simpler.

• Lower operational complexity - Modular monoliths reduce the operational overhead that comes with managing and deploying a distributed microservice system.

• Easier transition to microservices - Well-defined module boundaries make it straightforward to extract individual services and use microservices.

Monolith vs. Modular Monolith vs. Microservices

The biggest difference between modular monoliths and microservices is how they’re deployed.

Microservices use physical boundaries between services, while modular monoliths use logical boundaries.

With microservices, you have a clear strategy for modularity and structuring bounded contexts.

But, you can achieve this without building a distributed system.

The main problem is when people try to enforce code boundaries using microservices.

Instead, you can build a modular monolith to get almost the same benefits.

Modular monoliths give you high cohesion, low coupling, data encapsulation, focus on business functionalities, and more.

Microservices also give you independent deployments, independent scalability, and the ability to use a different tech stack per service.

You can think of the difference as a well-organized apartment (modular monolith) vs. a neighborhood of separate houses (microservices) - both have clear boundaries, but one is much simpler to maintain.

Choose microservices for the benefits, not because your monolithic codebase is a mess.
— Simon Brown

📌 TL;DR

• Modular monoliths offer a compelling way to structure applications.

• Modular monoliths offer most of the benefits of microservices without the complexity of distributed systems.

• Modular monoliths offer a smooth way to transition to microservices if needed.

• The main difference between microservices and modular monoliths is how they are deployed.

Hope this was helpful.

See you next week!

👋 Let’s connect

You can find me on LinkedIn, Twitter(X), Bluesky, or Threads.

I share daily practical tips to level up your skills and become a better engineer.

Thank you for being a great supporter, reader, and for your help in growing to 27.7K+ subscribers this week 🙏

Code review is a process that allows others to review your code changes.

The person who submits the code changes is referred to as the “Author”, while those reviewing the changes are referred to as “Reviewers”.

The primary purpose of code reviews is to:

Enhance the quality of the released solution and improve collaboration and knowledge transfer within the team.

However, doing code reviews right is not an easy task.

There are many problems related to code reviews, like wasted human effort and time, wrong focus → wrong results, communication breakdown, criticism, decreased developer productivity, and team velocity.

In today’s article, I’d like to share several code review guidelines, both for Authors and Reviewers, that I've seen working in teams and companies.

Let’s dive in!

The Hidden Cost of Broken Code Reviews

1. Reviews Become Time Sinks

• The average PR takes 2-4 days from submission to merge.

• Teams spend 8-12 hours per week on code reviews instead of building features.

2. Wrong Focus → Wrong Results

• Developers spend 50% of review time on formatting, naming conventions, and style preferences.

• Meanwhile, logic bugs, security vulnerabilities, and performance issues slide past because reviewers are mentally exhausted from nitpicking.

3. Communication Breakdown

• Authors write vague PR descriptions.

• Reviewers give unclear feedback and/or criticize the author.

• Nobody knows if an issue is critical or optional.

• Simple fixes turn into multi-day discussions.

• The cost isn’t just velocity—it’s team morale, code quality, and customer trust when bugs reach production.

Code reviews are expensive since there are many people involved in this activity.

That’s why I’m happy to partner with CodeRabbit on this newsletter.

With the help of CodeRabbit, I believe we can make them cheaper by automating the process, fixing the obvious problems, and focusing on the right things.

Try CodeRabbit

Best Practices for Authors:

• Review your own code changes and PR first before sharing with others.

  • Remove debug statements and commented code.

  • Check for obvious bugs or typos.

  • Consider using CodeRabbit for giving instant feedback.

    

• Ensure consistent naming and formatting.

  • Especially if your company follows a style guide.

• Test your code changes.

  • Both manually and with automated tests.

• Know what each new line does.

  • This is very crucial in the era of vibe coding.

• Automate the easy stuff.

  • Add formatters, linters, and rules to prevent nitpicking.

  • Consider using CodeRabbit for finding potential issues.

    

• Keep your code changes and PR small.

  • Research shows that review quality drops dramatically with the increasing number of files, lines, and changes. Ex: 400+ lines.

  • If your feature needs more code, break it into logical steps that can be reviewed independently.

• Write a clear PR description. Try to answer the questions:

  • What - “Add rate limiting to login endpoint...”

  • Why - “Prevent brute force attacks…”

  • How - “Implement rate limiting algorithms, block IPs…”

  • Testing - “Tested with 100 concurrent requests and verified…”

  • For visual changes, include relevant screenshots and/or videos that showcase the changes.

  • For bug fixes, outline the Before and After behaviors, and how you fixed them.

  • Consider using CodeRabbit for generating a summary of the changes.

    

• Document the non-obvious changes.

  • Try to answer questions with the code itself.

• Respond graciously to critiques.

  • Remember, it’s not about you, it’s about the code.

• If you’re confused, ask clarifying questions.

  • Don’t guess, ask questions instead.

  • Ex: "When you say 'this could be cleaner, ' do you mean splitting this function or renaming the variables?"

• Be patient when your reviewer is wrong.

  • Reviewers might be wrong due to a lack of context or experience, so try to provide it and help them understand your perspective.

• Minimize the lag between rounds of review.

  • Acknowledge feedback within 4 hours, even if you can’t fix everything immediately.

  • Quick responses show respect for your reviewer’s time.

• Consider doing a pair programming session with the reviewer if needed.

  • Peer code reviews work as a two-way transfer of knowledge when conducted carefully.

  • Both the reviewer and the author can learn new things, either for the project or in general.

Best Practices for Reviewers:

• Review PRs within 24 hours of submission.

  • This not only unblocks the author to merge their code but also speeds up the development process.

• Prioritize your review using this framework:

  • Correctness: Does the code work as intended?

  • Organization: Is it well-structured, maintainable, and follows the style guides?

  • Readability: Can the team and future me understand and modify this later?

  • Reliability: Is the solution fault-tolerant?

  • Scalability: Can the solution grow to accommodate higher future load?

  • Edge cases: What could go wrong in production?

• Prioritize your feedback:

  • Critical (must fix) - logic errors and bugs; security vulnerabilities; breaking changes; performance bottlenecks.

  • Important (should fix) - poor code organization; missing error handling; inadequate tests.

  • Suggestions (optional) - alternative implementations; style improvements; minor optimizations.

• Don’t make it personal! Review the code, not the author.

• Learn to give better feedback. Ask, don’t tell!

  

  • When you add a comment, have a strong WHY and a suggestion.

  • Mark more comments as NIT and don’t block PRs.

• Praise the good things.

  • Engineers, and people in general, tend to criticize when doing any kind of review, while forgetting to mention any good.

  • For the reviewer to be able to learn from the author, he should pay attention to the clever code as well, and it is a good habit to notice it.

• Consider doing a pair programming session with the reviewer if needed.

  • Sometimes, it’s better to sit together and resolve all issues instead of going through multiple rounds of reviews.

• When critical issues are resolved and code is “good enough” → Approve it.

• Code review is part of your job.

  • If you're not doing code reviews regularly, you are letting your teammates down.

CodeRabbit is an AI code review tool to reduce developer workload.

Here’s how it helps with code review flow:

• Do routine checks and reduce the time spent on reviews from days to minutes. Thus, improving developer velocity.

• Do consistent reviews without getting tired or biased. Thus, it reduces the risk of missing important issues due to human mistakes.

• Provide mentorship to junior engineers through detailed feedback.

Put simply, CodeRabbit complements human reviewers. It serves 1+ million repositories and has reviewed over 10 million pull requests. And it remains the most installed app on GitHub and GitLab.

📌 TL;DR

• Guidelines for Authors:

  • Review your own code changes and PR first.

  • Ensure consistent naming and formatting.

  • Test your code changes.

  • Know what each new line does.

  • Automate the easy stuff.

  • Keep your code changes and PR small.

  • Write a clear PR description.

  • Document the non-obvious changes.

  • Respond graciously to critiques.

  • If you’re confused, ask clarifying questions.

  • Be patient when your reviewer is wrong.

  • Minimize the lag between rounds of review.

• Guidelines for Reviewers:

  • Review PRs within 24 hours of submission.

  • Prioritize your review using a framework and quality attributes.

  • Prioritize your feedback.

  • Don’t make it personal! Review the code, not the author.

  • Learn to give better feedback. Ask, don’t tell!

  • Praise the good things.

  • When critical issues are resolved and code is “good enough” → Approve it.

  • Core reviews are part of your job.

Hope this was helpful.

See you next week!

Today’s action step: Take a look at your code review process and highlight areas for improvement. Try to follow or incorporate one of the mentioned tips in your daily routine.

👋 Let’s connect

You can find me on LinkedIn, Twitter(X), Bluesky, or Threads.

I share daily practical tips to level up your skills and become a better engineer.

Thank you for being a great supporter, reader, and for your help in growing to 27.5K+ subscribers this week 🙏

Clean Code is code that is easy to read, maintain, test, and understand.

Clean Functions are the foundation of Clean Code.

Master clean functions and you’ll naturally write better software.

In today’s article, I’ll share 8 practical tips for writing clean functions that I follow daily in my projects and work.

Let’s dive in!

Cut Code Review Time & Bugs in Half - Sponsor

CodeRabbit is your AI-powered code review co-pilot.

It provides instant, contextual feedback on every PR, along with one-click fix suggestions. It has reviewed over 10 million PRs and is used in 1 million repositories.

Besides, it’s free to use for open-source repos; 70K+ open-source projects already use it.

CodeRabbit lets you instantly spot:

• Logic & syntax bugs

• Security issues (XSS, SQL injection, CSRF)

• Concurrency problems (deadlocks, race conditions)

• Code smells & readability concerns

• Best practice violations (SOLID, DRY, KISS)

• Weak test coverage & performance bottlenecks

Write clean, secure, and performant code with CodeRabbit.

Try CodeRabbit Now

#1: Keep Your Functions Small And Focused

Functions that do multiple things are hard to follow, understand, test, debug, and even reuse.

When something breaks, it’s very hard to pinpoint the exact part that failed.

When requirements change, and they do change regularly, you risk breaking the whole function and unrelated functionality.

In the Clean Code book, Uncle Bob says:

The first rule of functions is that they should be small.
The second rule of functions is that they should be smaller than that.

So each function should have one clear responsibility.

Sometimes a function might be just 5 lines of code, while other times it might be 50 lines of code to fulfill a single responsibility.

If you can describe what your function does with “and”, it probably does too much.

There’s no universal rule to draw the line.

Trust your experience and your judgment based on the context you have.

Be pragmatic. Don’t be dogmatic.

#2: Name Functions to Reveal Intent

Function names like process() or handle() force readers to examine the implementation to understand what the function does.

This slows down code reading and increases the cognitive load.

Function names should clearly state what they do with action verbs.

A good function name should answer:
“What action does this perform?” and “What does it return?”

You can also follow these tips:

• Use terms and language based on the specific domain, so your functions are more tailored to the business context.

• Follow the already established naming conventions.

• Use verbs and verb phrases for actions (calculate, validate, send).

• Use question words for boolean functions (is, has, can).

• Be consistent with the naming, so you don’t use two words for the same thing.

#3: Return Early to Avoid Nesting

Deeply nested functions create a “pyramid of doom”, which is hard to follow, debug, and understand.

Your brain has to track multiple logical branches simultaneously.

The main business logic gets “hidden”, making it hard to find.

To fix this, you can use the early return principle.

You can handle edge cases and invalid inputs using guard clauses.

This removes the many levels of branches, keeping the “happy path” obvious, clear, and easy to follow.

#4: Limit Function Parameters

Functions with many parameters are a cognitive load.

You can’t remember parameter order, and it’s easy to pass the wrong values.

To improve this, group related parameters into objects.

This reduces cognitive load and makes parameter order irrelevant.

#5: Write Pure Functions When Possible

Functions with side effects are unpredictable.

They might work differently based on a global state, making them hard to test and debug.

You can’t reason about them in isolation.

They also cause mysterious bugs in unrelated parts of the system.

To mitigate this problem, strive to write functions that depend only on their inputs and produce no side effects.

Pure functions are predictable, testable, and can be safely called from anywhere.

And we can also run them in parallel.

#6: Avoid Boolean Parameters

Boolean parameters make function calls unclear and hard to extend.

When you see processOrder(order, true), you can’t tell what true means without checking the function definition.

Boolean flags also often indicate that a function is doing two different things.

A better approach is to use objects, enums, or separate functions instead of single boolean flags.

This makes your code self-documenting and easier to extend.

#7: Return Results, Not Exceptions

Using exceptions for expected failures makes error handling invisible and easy to forget.

Callers don’t know what can go wrong just by looking at the function signature.

This leads to unhandled edge cases and application crashes.

To fix this, apply the Result Pattern and make errors part of your return type.

This forces callers to handle error cases and makes your function’s behaviour predictable and explicit.

A good rule of thumb is:

Use Result Pattern for expected errors to make them explicit.

Use Exceptions for unexpected errors and exceptional situations.

#8: Replace Magic Numbers and Strings

A common code smell is the use of magic numbers and strings.

These hardcoded values create a maintenance nightmare.

When business requirements and rules change, it’s very hard to find every occurrence of these numbers or strings.

Another big problem with these magic numbers and strings is the lack of meaning.

To fix this problem, extract the numbers into constants and the strings into enums.

📌 TL;DR

That’s all for today, 8 tips to write clean functions:

• #1: Keep Your Functions Small And Focused

• #2: Name Functions to Reveal Intent

• #3: Return Early to Avoid Nesting

• #4: Limit Function Parameters

• #5: Write Pure Functions When Possible

• #6: Avoid Boolean Parameters

• #7: Return Results, Not Exceptions

• #8: Replace Magic Numbers and Strings

Hope this was helpful.

See you next week!

Today’s action step: Take a look at your project and see if you’re making some of the mistakes I highlighted here. Try to fix them using the clean code tips I shared with you.

👋 Let’s connect

You can find me on LinkedIn, Twitter(X), Bluesky, or Threads.

I share daily practical tips to level up your skills and become a better engineer.

Thank you for being a great supporter, reader, and for your help in growing to 27.4K+ subscribers this week 🙏