DEV Community: Code Atlas

Naming Things Without Pain

Code Atlas — Wed, 16 Sep 2026 08:00:44 +0000

Naming is the part of programming nobody puts on a roadmap, yet it eats a surprising chunk of my day. I used to stare at a blinking cursor naming a variable for five minutes, then rename it three times in code review. Here is what actually reduced that friction for me.

The two rules that kill most bikeshedding

1. Name the thing by what it is, not what it does. A boolean is a fact about the world, so it reads as a claim: isLoading, hasPermission, canEdit. If you find yourself writing checkPermission, you probably want a function, not a flag.

2. Length should match scope. A loop index can be i. A variable used three lines later can be id. A module-level export that appears in 40 files needs to carry its context: InvoicePaymentStatus, not Status.

That second rule is the one people violate most. Short names are not a virtue in themselves. They are a budget you spend on small scopes.

Pick a shape and stick to it

Consistency beats cleverness. I keep a tiny mental table:

// booleans: is/has/can/should
const isDirty = true;
const hasAccess = user.role === 'admin';

// functions: verb first
function parseConfig(raw) {}
function fetchUserById(id) {}

// collections: plural
const activeUsers = [];
const userById = new Map();

// handlers: on + event
function onSaveClick() {}

Once the shape is decided, naming becomes filling in a blank instead of an open-ended creative act. fetch___ById is much easier to finish than "what do I call this function."

Say the call site out loud

The fastest naming test I know: read the line where the thing is used, not where it is defined.

// Reads badly
if (data.flag) { ... }

// Reads fine
if (user.isEmailVerified) { ... }

The definition site is where you have the most context. The call site is where the next person has the least. Optimize for the reader who is 200 lines away and has forgotten everything.

Don't encode the type

I stopped doing this years ago and never missed it:

// Redundant, and lies the moment the type changes
const userListArray = [];
const nameString = 'Ada';

// Just say what it holds
const users = [];
const name = 'Ada';

Types change. userListArray becomes a Set and now the name is a bug you have to remember to fix. The same goes for IUser style prefixes and str/int suffixes.

When the name is hard, the design is usually the problem

This is the insight that saved me the most time. If I cannot name something cleanly, it is almost always because it is doing two jobs.

A function called processAndValidateOrder is a smell. Split it:

function validateOrder(order) { /* returns errors */ }
function processOrder(order) { /* assumes valid */ }

Now both names are obvious because both functions have one responsibility. Naming pain is often a design signal wearing a costume.

Rename aggressively, and let the tool do it

I used to avoid renaming because of the churn. Modern editors make it a non-event: rename the symbol, run the tests, commit. The cost of a slightly wrong name is that every future reader pays it. The cost of a rename is one commit.

I do not try to get the name perfect on the first pass. I write thing or tmp, get the logic working, then rename once I understand what the code actually does. Naming is easier after the code exists, not before.

A short checklist I actually use

Does it read well at the call site?
Is it a fact (boolean) or an action (function)?
Is the length right for its scope?
Does it avoid encoding the type?
If it is hard to name, is it doing too much?

That last question resolves most of my naming stalls. When nothing fits, I stop trying to name the function and start asking why it is so hard to describe. Usually the answer is: because it is two things, and I should split it first.

A Git Workflow That Actually Works for Small Teams

Code Atlas — Sat, 12 Sep 2026 08:00:59 +0000

Most Git workflow advice online is written for teams of 50. If you are 3 to 8 developers shipping to production several times a week, GitFlow is ceremony you do not need, and pure trunk-based development can feel reckless. Here is the middle ground my teams have settled on.

The shape of it

One long-lived branch: main. It is always deployable. Everything else is a short-lived branch that lives hours to two days, merges via pull request, and gets deleted.

main ──●──●────●────●──●──●──▶
        \        /    \    /
         ●──●──●      ●──●
        feature       fix

No develop. No release/* unless you genuinely ship versioned artifacts. The fewer branches that must stay in sync, the fewer merge conflicts you will ever resolve.

Branch naming

Use a prefix that maps to your tracker. It costs nothing and makes git branch readable:

git switch -c feat/invite-teammates
git switch -c fix/webhook-timeout
git switch -c chore/bump-node

feat/, fix/, and chore/ cover 95% of real work.

Keep branches short

This is the single rule that matters most. A branch open for a week is a branch that will conflict. Break work into slices you can merge independently. If a feature needs a database migration, a backend endpoint, and a UI, merge the migration first, then the endpoint, then the UI. Each PR should be reviewable in under 20 minutes.

Rebase, do not merge, when syncing

While your branch is open, keep it current with main by rebasing:

git fetch origin
git rebase origin/main

This keeps history linear and makes review diffs honest. If you have already pushed and someone else pulled your branch, use --force-with-lease instead of --force so you do not clobber their work:

git push --force-with-lease

When the PR is approved, merge into main. Pick one strategy and never debate it again. We squash merge, so main gets one commit per PR with a clean message. If you prefer merge commits, that is fine too. Consistency beats correctness here.

Protect main, but lightly

On GitHub or GitLab, require:

At least one approving review
Passing CI
Branch up to date before merge

That is it. Do not require two reviewers on a team of four. Do not require signed commits on day one. Every gate you add slows the loop, and small teams win by keeping the loop fast.

Write commits that help future you

Use Conventional Commits so changelogs and semantic versioning can be automated later:

feat: add teammate invite flow

Sends an email with a signed token. Token expires in 24h.

Squash merges mean the PR title becomes the commit, so enforce the same convention on PR titles.

Tag releases

When you deploy, tag it:

git tag -a v1.4.0 -m "Add teammate invites"
git push origin v1.4.0

Tags are your rollback anchors. When something breaks at 2am, git checkout v1.3.2 beats scrolling through 400 commits.

Hotfixes

Branch off main, fix, PR, merge, deploy, tag. No special hotfix branch. The process is identical to any other change, which means nobody has to remember a different procedure under pressure.

What to skip

develop branch: it just delays integration
Long-lived feature branches: they rot
Release branches: only worth it if you ship binaries with backports
Strict GitFlow: built for scheduled releases, not continuous deploys

The daily loop

git switch main && git pull
git switch -c feat/something
git commit -am "feat: something"
git fetch origin && git rebase origin/main
git push -u origin feat/something
# open PR, get review, squash merge, delete branch

That is the whole workflow. The best process for a small team is the one nobody has to think about. Keep branches short, keep main green, and spend your energy on the product instead of on Git.

For the commands themselves, the official Git reference is still the best source.

Testing Basics That Actually Pay Off

Code Atlas — Thu, 10 Sep 2026 16:01:14 +0000

I've written a lot of tests that did nothing but slow down CI. And a few that saved me at 2am before a deploy. The difference was never fancy tooling. It was picking the right things to test and keeping the tests honest.

Here's what I actually reach for now.

Test behavior, not implementation

The fastest way to make a test suite worthless is to assert on how code does something instead of what it does. If I refactor a function and 12 tests break for no real reason, those tests are liabilities.

Bad: asserting a helper was called twice. Good: asserting the output is correct.

// Fragile: tied to implementation
it('calls formatName once', () => {
  const spy = jest.spyOn(utils, 'formatName');
  greet('ada');
  expect(spy).toHaveBeenCalledTimes(1);
});

// Durable: tied to behavior
it('greets by first name', () => {
  expect(greet('Ada Lovelace')).toBe('Hello, Ada');
});

The second test survives a rewrite of formatName. The first one just tells you the internals changed.

The pyramid is real, but lopsided

I don't chase ratios. I do follow one rule: push logic into pure functions and test those hard, then keep a thin layer of integration tests around the wiring.

Pure functions are cheap to test, fast, and deterministic. Most of my bugs live in edge cases of string parsing, date math, and money rounding. Those are all pure. So that's where my test count actually goes.

from decimal import Decimal

def apply_discount(price: Decimal, pct: Decimal) -> Decimal:
    if pct < 0 or pct > 100:
        raise ValueError('pct out of range')
    return (price * (100 - pct) / 100).quantize(Decimal('0.01'))

# The tests that earn their keep
def test_no_discount():
    assert apply_discount(Decimal('10.00'), Decimal('0')) == Decimal('10.00')

def test_rounds_half_up():
    assert apply_discount(Decimal('9.99'), Decimal('15')) == Decimal('8.49')

def test_rejects_bad_range():
    import pytest
    with pytest.raises(ValueError):
        apply_discount(Decimal('10'), Decimal('150'))

Three tests, all about behavior, all fast.

Test the edges, not the middle

The happy path usually works. The bug is in empty strings, zero, negative numbers, unicode, timezones, and the off-by-one at the boundary. When I write a new function I ask: what inputs would surprise me? Then I write those tests first.

A quick checklist I run through:

Empty and single-element collections
Zero, negative, and very large numbers
Null or missing optional fields
Boundaries: exactly at the limit, one past it
Ordering: does the result depend on input order?

Make failures readable

A test that fails with expected true, got false costs me ten minutes. A test that fails with the actual value costs me ten seconds. Assert on specific values, not just truthiness.

// Useless on failure
expect(result).toBeTruthy();

// Tells you what happened
expect(result).toEqual({ id: 42, status: 'active' });

Same for messages. If I'm testing that an error is thrown, I check the message contains something meaningful, not just that some error happened.

Determinism beats cleverness

Any test that depends on the current time, network, random seed, or filesystem order will flake. Flaky tests get muted, and muted tests are dead tests.

Inject the clock. Inject the ID generator. Seed the RNG. It's a small refactor and it turns a suite you ignore into one you trust.

// Before: untestable
function createOrder(items) {
  return { id: crypto.randomUUID(), createdAt: new Date(), items };
}

// After: injectable
function createOrder(items, { id, now }) {
  return { id, createdAt: now, items };
}

Now the test is a pure function call with no surprises.

Run them fast, run them often

If the suite takes more than a few seconds, people stop running it locally. Keep unit tests under a second or two total. Push slow integration tests behind a separate command. The best test suite is the one that actually runs on every save.

What I skip

I don't test getters, framework glue, or trivial one-line wrappers. I don't chase 100% coverage. Coverage tells you what ran, not what's correct. A line can be executed and still be wrong.

I do test anything with a branch, a calculation, or a boundary. That's where the money is.

The short version

Test behavior, not internals
Push logic into pure functions and test those hard
Cover edges and boundaries first
Assert on specific values so failures are readable
Remove time, randomness, and I/O from the equation
Keep the fast tests fast so you actually run them

None of this is exotic. It's just the stuff that keeps paying off long after the initial novelty of a test framework wears off.

Error Handling Patterns That Actually Scale

Code Atlas — Wed, 09 Sep 2026 00:00:45 +0000

Start With the Problem

Error handling is one of those things that seems trivial until it bites you. Early in my career, I wrote code that checked for errors at every step but handled them inconsistently. Some functions returned null, others threw exceptions, and a few just logged and continued. The result? A debugging nightmare where the real issue was buried under layers of defensive checks.

After years of maintaining and building systems, I've settled on a few patterns that make error handling predictable and scalable. Here's what works.

Pattern 1: Fail Fast, But Fail Loudly

The worst errors are silent ones. A function that returns undefined when something goes wrong often leads to a cryptic error later, far from the actual cause. Instead, validate inputs early and throw descriptive exceptions immediately.

function getUser(id) {
  if (!id || typeof id !== 'string') {
    throw new Error(`Invalid user ID: ${id}`);
  }
  // ... rest of logic
}

This pattern forces the caller to handle the error at the point of failure, not five stack frames down. It also makes your function's contract explicit: if you pass bad data, you get an immediate, clear signal.

Pattern 2: Use Result Objects for Expected Failures

Not all errors are exceptional. Network requests can fail, files might not exist, and user input can be invalid. For these expected failures, exceptions are overkill. They interrupt control flow and make the happy path hard to follow.

Instead, use a result object that explicitly carries either a value or an error.

type Result<T> = { ok: true; value: T } | { ok: false; error: Error };

function parseJson(raw: string): Result<unknown> {
  try {
    return { ok: true, value: JSON.parse(raw) };
  } catch (err) {
    return { ok: false, error: err as Error };
  }
}

The caller must check .ok before using the value. This makes the potential failure visible in the type signature and prevents accidental unhandled errors.

Pattern 3: Centralized Error Handling in Async Flows

In async code, errors can slip through if you don't catch them everywhere. Instead of wrapping every await in a try/catch, centralize error handling at the boundary of your application or service.

async function handleRequest(req, res) {
  try {
    const data = await fetchData(req.params.id);
    res.json(data);
  } catch (err) {
    // Log with context, then send a generic response
    console.error('Request failed:', req.path, err);
    res.status(500).json({ message: 'Internal server error' });
  }
}

If you're using Express, you can even use an async wrapper to avoid repeating try/catch in every route.

const asyncHandler = (fn) => (req, res, next) => {
  Promise.resolve(fn(req, res, next)).catch(next);
};

app.get('/user/:id', asyncHandler(async (req, res) => {
  const user = await getUser(req.params.id);
  res.json(user);
}));

Then a single error-handling middleware takes care of logging and responding consistently.

Pattern 4: Preserve Error Context

When you catch an error and rethrow a new one, don't lose the original stack trace. Wrap it properly.

try {
  await db.query(...);
} catch (err) {
  throw new Error(`Failed to query database for user ${userId}`, { cause: err });
}

Modern JavaScript supports the cause option, which preserves the original error. This gives you both a high-level description and the low-level details when debugging.

Pattern 5: Don't Swallow Errors Silently

Empty catch blocks are a code smell. If you catch an error, do something with it: log it, rethrow it, or convert it to a meaningful response. Swallowing errors hides bugs and makes systems appear healthy when they're not.

// Bad
catch (err) {}

// Better
catch (err) {
  logger.warn('Non-critical operation failed', { error: err.message });
  // continue with fallback
}

Putting It All Together

A pragmatic approach is to classify errors:

Programmer errors: bugs like null dereferences. Fail fast, crash the process, fix the code.
Operational errors: things like network timeouts. Use result objects or retries.
User input errors: validation failures. Return early with a clear message.

By separating these, you avoid over-engineering while keeping your code resilient. Start with one or two of these patterns in your next project and see how much easier debugging becomes.

Error handling isn't glamorous, but it's the difference between a system that's a joy to maintain and one that keeps you up at night. Choose patterns that make failure visible, explicit, and easy to trace.

Naming Things Without Pain: A Practical Guide

Code Atlas — Sat, 05 Sep 2026 00:00:31 +0000

Naming Things Without Pain

We've all been there: staring at a variable called data or a function called process() and wondering what the original author was thinking. Naming is one of the hardest parts of programming, but it doesn't have to be a constant source of frustration. Here's a practical approach I've refined over years of writing and reviewing code.

1. Name for the Reader, Not the Writer

When you name something, you're writing a tiny piece of documentation. The reader is usually your future self, six months from now, or a teammate who's never seen this code. Ask: "If I read this name in a vacuum, would I know what it does or represents?"

# Bad: what does this do?
x = get_stuff()

# Better: clear intent
user_posts = fetch_posts_for_user(user_id)

2. Use Meaningful Distinctions

Avoid names that differ only by a number or a vague qualifier. data1, data2, temp, temp2 are all red flags. Instead, be explicit about what's different.

// Bad
const list1 = [1, 2, 3];
const list2 = [4, 5, 6];

// Better
const primeNumbers = [2, 3, 5];
const evenNumbers = [4, 6, 8];

3. Follow the Principle of Least Surprise

A name should not mislead. If a function is called getUser, it should return a user, not update one. If a variable is called isActive, it should be a boolean. Consistency with language conventions matters too: in most languages, is or has prefixes imply a boolean.

# Bad: this returns a boolean but sounds like an action
def delete_confirmation?
  # ...
end

# Better
def confirmed_to_delete?
  # ...
end

4. Use the Right Level of Abstraction

Names should reflect the level of abstraction you're working at. In a low-level utility, buffer is fine. In a business logic layer, pending_order is better than p. Don't over-abstract either: thing or item are rarely useful.

5. Avoid Disinformation

Don't use names that are easily confused with each other or with built-in keywords. For example, account and accounts are too close, especially in large codebases. Also avoid using list as a variable name in Python because it shadows the built-in type.

6. Use Pronounceable and Searchable Names

If you can't say it out loud, it's hard to discuss in code review. genymdhms (generation date, year, month, day, hour, minute, second) is a classic anti-pattern. Also, names like x are hard to search for because they appear everywhere. Use names that you can grep for uniquely.

// Bad
var y = DateTime.Now.AddDays(7);

// Better
var expirationDate = DateTime.Now.AddDays(7);

7. Use One Word per Concept

Pick a vocabulary and stick to it. If you use fetch, get, and retrieve interchangeably, readers will wonder if there's a subtle difference. Choose one word for each concept and use it consistently across your codebase.

// Bad: mixing synonyms
User user = userRepository.fetch(id);
Order order = orderService.get(id);

// Better: pick one
User user = userRepository.get(id);
Order order = orderService.get(id);

8. For Booleans, Use Positive Names When Possible

Negative names like notFound or isInvalid are harder to read in conditions. Prefer positive ones and use ! when you need negation.

# Bad
if not is_not_found:
    pass

# Better
if is_found:
    pass

9. Don't Be Afraid to Rename

If you notice a bad name during code review, fix it. If you're refactoring and a name no longer fits, change it. Modern IDEs make renaming safe and fast. Leaving a bad name because "it's already there" accumulates technical debt.

10. When in Doubt, Ask

If you're unsure what to name something, ask a teammate or write a comment explaining what it does. Sometimes the act of describing it helps you find the right name. You can also use a placeholder like TODO: rename but don't leave it forever.

A Simple Heuristic

If you can't come up with a good name within a few minutes, you might not understand the problem well enough. Step back and revisit what the function or variable really does. Often, a good name emerges once you clarify the intent.

Naming is a skill, not a talent. With practice and intentionality, you can write code that reads like a well-structured story. Your future self will thank you.

For more on this topic, check out the classic book Clean Code by Robert C. Martin, which has an entire chapter on meaningful names. Also, the Google Style Guides offer language-specific naming conventions that are worth following.

Refactoring Safely: A Step-by-Step Guide

Code Atlas — Thu, 03 Sep 2026 16:00:32 +0000

Refactoring Safely: A Step-by-Step Guide

We all know that feeling: a function that's 200 lines long, a class that does too many things, or a variable named data2. Refactoring is the cure, but doing it recklessly can break your app and your confidence. Here's how I approach refactoring safely, step by step.

1. Start with a Safety Net

Before touching any code, make sure you have tests. If your project lacks tests, write a few key ones first. Focus on the behavior you're about to change. The goal is to have a safety net that tells you when you've broken something.

# example test for a function we'll refactor
import unittest
from mymodule import calculate_total

class TestCalculateTotal(unittest.TestCase):
    def test_with_discount(self):
        self.assertEqual(calculate_total(100, discount=0.1), 90)

If tests aren't feasible, at least have a manual checklist. But automated tests are worth the effort.

2. Make Small, Atomic Changes

Don't try to refactor everything at once. Pick one logical change. For instance, extract a method or rename a variable. Each change should be small enough that if it breaks, you know exactly what caused it.

// before
function processOrder(order) {
  const total = order.items.reduce((sum, item) => sum + item.price, 0);
  const tax = total * 0.08;
  const final = total + tax;
  return final;
}

// after step 1: extract tax calculation
function processOrder(order) {
  const total = order.items.reduce((sum, item) => sum + item.price, 0);
  const final = total + calculateTax(total);
  return final;
}

function calculateTax(amount) {
  return amount * 0.08;
}

Run your tests after each tiny step. If they pass, move on. If they fail, you know the last change caused it.

3. Use Your IDE's Refactoring Tools

Modern IDEs can rename variables, extract methods, and change signatures safely. They update all references automatically. This reduces human error. For example, in VS Code, right-click a function and choose "Extract to method" or use F2 to rename a symbol across files.

But be careful: tools aren't perfect. Always review the diff and run tests after using them.

4. Keep Behavior Identical

Refactoring should not change observable behavior. If you're fixing a bug, that's not refactoring, it's a fix. When refactoring, the tests should still pass without modifying them (unless you're also adding new tests for new behavior). If you need to change tests to make them pass, you might be changing behavior inadvertently.

5. Commit Frequently

Make a commit after each successful small step. This gives you checkpoints to revert to. If something goes wrong later, you can git bisect or simply revert to the last good commit. I usually commit after every 10-15 minutes of refactoring work.

git add .
git commit -m "Extract calculateTax method"

6. Use Feature Flags for Risky Changes

If you're refactoring a critical path, consider hiding the new code behind a feature flag. This way you can ship the refactor to production but toggle it off if problems arise. It's a bit more overhead, but for high-risk changes it's worth it.

const useNewLogic = process.env.FEATURE_NEW_LOGIC === 'true';

function processOrder(order) {
  if (useNewLogic) {
    return processOrderNew(order);
  }
  return processOrderOld(order);
}

7. Keep an Eye on Performance

Sometimes refactoring can accidentally degrade performance. For example, extracting a method might cause extra object allocation. If performance is critical, profile before and after. But don't optimize prematurely; most refactors don't affect performance noticeably.

8. Refactor in Stages

If you have a large refactor, break it into stages. For example, first rename variables, then extract methods, then change architecture. Each stage should leave the code in a working state. This is sometimes called the "strangler fig" pattern: gradually replace parts without a big bang.

9. Review Your Own Diff

Before committing, review the diff. Does it make sense? Are there any accidental changes? Sometimes you might have changed formatting or whitespace. If so, revert those unrelated changes to keep the diff clean.

10. Ask for a Code Review

A second pair of eyes can spot issues you missed. Even if you're confident, a quick review can catch subtle behavior changes or style inconsistencies. It also spreads knowledge about the codebase.

Conclusion

Refactoring is a discipline, not a chore. By working in small steps, keeping tests green, and using tools wisely, you can improve your code without fear. The key is to make the change so small that if it breaks, the fix is obvious. Over time, you'll build confidence and your codebase will become cleaner and more maintainable. Happy refactoring!

Error Handling Patterns That Actually Scale

Code Atlas — Tue, 01 Sep 2026 16:00:34 +0000

Start With the End in Mind

Every error handling pattern I've seen fail has one thing in common: it was bolted on after the happy path was done. When you write try/catch as an afterthought, you end up with inconsistent handling, swallowed exceptions, and debugging sessions that make you question your career.

Instead, decide your error strategy before you write the first function. That doesn't mean planning every edge case upfront, but it means agreeing on the shape of errors, who handles them, and how they surface.

The Three Layers of Error Handling

I mentally split error handling into three layers: detection, propagation, and presentation. Each layer has its own job, and mixing them is where things get messy.

Detection is where the error happens. It's the throw or the return of a failure. Propagation is how the error travels up the call stack, either through exceptions, result objects, or callbacks. Presentation is what the user sees or what the log records.

Most codebases fail because they try to do all three in the same place. A function that catches, logs, formats, and rethrows is doing too much.

Exceptions vs. Result Objects

The classic debate: should you throw or return a result? Both work, but they have different trade-offs.

Exceptions are great for truly exceptional conditions: network drops, disk full, programmer bugs. They let you skip straight to an error handler without threading checks through every function. But they're terrible for expected failures like validation errors, because they force callers to remember to catch them.

Result objects (like Either, Result, or a simple { ok, value, error }) make expected failures explicit. The type system reminds you that a function can fail. The downside is verbosity, especially in languages without pattern matching.

My rule of thumb: throw for what you can't prevent, return for what you can. If a user submits a bad email, that's a return. If the database goes down, that's a throw.

The Return Pattern That Works

Here's a simple result pattern in TypeScript that I've used in production:

type Result<T> = { ok: true; value: T } | { ok: false; error: Error };

function parseConfig(raw: string): Result<Config> {
  try {
    const data = JSON.parse(raw);
    return { ok: true, value: data };
  } catch (e) {
    return { ok: false, error: new Error(`Invalid config: ${e.message}`) };
  }
}

function loadConfig(filePath: string): Result<Config> {
  const raw = readFile(filePath);
  if (!raw.ok) return raw;
  return parseConfig(raw.value);
}

Notice how loadConfig doesn't catch anything. It just propagates the error. The caller decides what to do:

const config = loadConfig('./app.json');
if (!config.ok) {
  console.error(config.error.message);
  process.exit(1);
}

This pattern scales because every function returns a consistent shape. You never have to guess whether a function throws or returns null.

Error Wrapping: Add Context, Not Noise

When an error bubbles up, it's tempting to wrap it in a generic message like "Something went wrong." That's noise. Instead, wrap with context that helps debugging: what operation failed, what were the inputs, what was the state.

def fetch_user(user_id: int) -> User:
    try:
        response = api.get(f"/users/{user_id}")
        response.raise_for_status()
        return response.json()
    except HTTPError as e:
        raise UserFetchError(f"Failed to fetch user {user_id}") from e

The from e in Python preserves the original traceback. In JavaScript, you can set the cause property:

try {
  await api.get(`/users/${id}`);
} catch (e) {
  throw new Error(`Failed to fetch user ${id}`, { cause: e });
}

Now your logs show the chain: UserFetchError -> HTTPError -> original network error. That's gold when you're paging through logs at 2am.

The Catch-All That Kills

A bare catch {} or except: is almost always wrong. It hides bugs and makes your system look healthy when it's not. If you must catch everything, at least log it and rethrow or convert to a known error type.

// Bad: swallows everything
try {
  riskyOperation();
} catch {}

// Better: log and rethrow as a known type
import { logger } from './logger';

try {
  riskyOperation();
} catch (e) {
  logger.error('riskyOperation failed', e);
  throw new AppError('riskyOperation failed', { cause: e });
}

Centralize Error Handling at the Boundary

Don't scatter try/catch in every controller or event handler. Instead, have a single place that handles errors for each layer: an Express middleware, a React error boundary, a Kafka consumer wrapper.

In Express, you can have an error-handling middleware:

app.use((err, req, res, next) => {
  if (err instanceof ValidationError) {
    return res.status(400).json({ error: err.message });
  }
  logger.error('Unhandled error', err);
  res.status(500).json({ error: 'Internal server error' });
});

This way, your business logic can throw or return errors without worrying about HTTP status codes. The boundary maps errors to responses.

Avoid the Pyramid of Doom

Nested try/catch blocks are a code smell. If you find yourself nesting, extract a function or use a pattern like the result object to flatten the flow.

// Bad: nested
try {
  const a = tryA();
  try {
    const b = tryB(a);
  } catch (e) { /* handle B */ }
} catch (e) { /* handle A */ }

// Better: separate functions with their own error handling
function doA() { try { return tryA(); } catch (e) { throw new AError(e); } }
function doB(a) { try { return tryB(a); } catch (e) { throw new BError(e); } }

function main() {
  const a = doA();
  const b = doB(a);
}

Test Your Error Paths

Errors are code paths too. If you don't test them, they will break in production. Write tests that force failures: mock the API to return 500, simulate a full disk, pass invalid input.

def test_fetch_user_handles_http_error(mocker):
    mocker.patch('api.get', side_effect=HTTPError('boom'))
    with pytest.raises(UserFetchError):
        fetch_user(1)

Keep It Simple

There's no one-size-fits-all pattern. But the principles hold: be explicit, add context, centralize, and test. Start with a simple result object for expected failures, use exceptions for the unexpected, and wrap at boundaries. Your future self will thank you when you're debugging a production issue with a clear error chain instead of a silent catch {}.

Error Handling Patterns That Actually Scale

Code Atlas — Fri, 28 Aug 2026 16:01:30 +0000

Error Handling Patterns That Actually Scale

Every codebase starts with try/catch sprinkled around, and it works until it doesn't. Once you hit a certain size, inconsistent error handling becomes a source of bugs, not a cure. Here are the patterns I've found that hold up in production.

1. Fail Fast vs. Fail Gracefully

Decide early which operations are critical and which are optional. For critical paths (e.g., database connection), fail fast: throw immediately and let the process crash or restart. For non-critical (e.g., sending a notification), fail gracefully: log and continue.

// Fail fast
const db = connectDB(); // throws if unavailable

// Fail gracefully
sendEmail(user.email).catch(err => {
  logger.warn('Email failed', { err, userId: user.id });
});

Mixing these up leads to silent data loss or unnecessary crashes. Write it in your README.

2. The Result Object Pattern

Instead of throwing exceptions for expected failures (validation, not found), return a structured result. This makes control flow explicit and avoids the "throw for everything" trap.

type Result<T> = { ok: true; value: T } | { ok: false; error: Error };

function findUser(id: string): Result<User> {
  const user = db.find(id);
  if (!user) return { ok: false, error: new Error('User not found') };
  return { ok: true, value: user };
}

// Usage
const result = findUser('123');
if (!result.ok) {
  // handle expected miss
} else {
  // use result.value
}

This pattern shines in languages without checked exceptions. It forces callers to handle the error case at compile time (if you're using TypeScript) and makes the happy path obvious.

3. Centralized Error Handling in Async Code

In Node.js, unhandled promise rejections crash processes. Don't rely on process.on('unhandledRejection') as a band-aid; instead, wrap your async entry points.

async function main() {
  try {
    await startServer();
  } catch (err) {
    logger.fatal('Server crashed', { err });
    process.exit(1);
  }
}

main();

For Express, use an error-handling middleware as the single place to format responses and log.

app.use((err, req, res, next) => {
  logger.error('Request failed', { err, path: req.path });
  res.status(err.status || 500).json({ message: err.message });
});

Never log the same error in multiple places; you'll get duplicate logs and lose the original stack.

4. Wrap External Calls

Third-party APIs and SDKs throw their own error types. Wrap them in a domain error so your business logic doesn't depend on library specifics.

class PaymentError(Exception):
    pass

def charge_card(card):
    try:
        stripe.Charge.create(...)
    except stripe.error.CardError as e:
        raise PaymentError(f"Card declined: {e.message}") from e
    except stripe.error.APIConnectionError:
        raise PaymentError("Payment service unreachable") from e

This also lets you add context (like user ID) at the boundary, which is invaluable when debugging.

5. Logging: Include Context, Not Just Messages

A log line like "Error: something went wrong" is useless. Include the operation, IDs, and any relevant state. Use structured logging (JSON) so you can query later.

logger.error('Failed to process order', {
  orderId: order.id,
  userId: order.userId,
  error: err.message,
  stack: err.stack,
});

Avoid logging sensitive data (passwords, tokens) and avoid logging the same error at multiple levels.

6. Retry with Exponential Backoff

Transient failures (network hiccups, timeouts) are common. Implement retries with jitter to avoid thundering herds.

import time
import random

def retry(fn, attempts=3, base_delay=0.1):
    for i in range(attempts):
        try:
            return fn()
        except Exception:
            if i == attempts - 1:
                raise
            delay = base_delay * (2 ** i) + random.uniform(0, 0.1)
            time.sleep(delay)

Only retry idempotent operations. If the operation isn't idempotent, you'll double-charge or duplicate writes.

7. Don't Swallow Errors

An empty catch {} is a bug waiting to happen. If you catch, you must handle or rethrow. If you truly want to ignore (rare), comment why.

try {
  await trackEvent();
} catch (err) {
  // Analytics must never break the main flow
  logger.debug('Analytics failed', { err });
}

Final Thought

The goal isn't to eliminate errors; it's to make them predictable and observable. Pick a few patterns, apply them consistently, and revisit your error handling when you add new features. Your future self will thank you.

For more on JavaScript promises, see the MDN guide on using promises.

Design Functions That Compound

Code Atlas — Thu, 27 Aug 2026 08:00:31 +0000

Start with the Caller

When I write a function, I try to think about how I want to call it from the outside before I write a single line of the body. That shift in perspective changed my code quality more than any linting rule or design pattern. The function signature is the contract, and the body is just the implementation. If the signature is awkward, the body will be too.

A good signature reads like a sentence. It tells you what goes in and what comes out without forcing you to read the implementation. For example:

# Bad: unclear what the return value represents
def process(data, flag):
    ...

# Good: the name and parameters tell the story
def build_report(transactions, include_totals=False):
    ...

This clarity compounds. Every function you write becomes a building block for the next one. If the building blocks are clean, the higher-level code becomes a pleasure to read.

One Job, One Level of Abstraction

You've heard "single responsibility" before, but it's easy to slip. The real test is whether you can describe the function in one sentence without using "and" or "then".

// Bad: does three things
function updateUserAndSendEmail(user, changes) {
  // update db
  // send email
  // log
}

// Good: separate functions, each with one job
function applyUserChanges(user, changes) { /* ... */ }
function notifyUser(user) { /* ... */ }

Also, keep the body at a consistent level of abstraction. If your function is about business logic, don't drop down to string manipulation or low-level array indexing. Extract those into helpers. This makes the main flow read like a high-level summary.

Naming Is Design

Names are not just for humans; they guide future refactoring. A good name reveals intent and makes the function self-documenting.

Use verbs for actions: calculateTotal, fetchUser, validateInput.
Use nouns for things: getUserById might return a user, but userById is ambiguous.
Avoid generic words like data, info, stuff. They hide meaning.

Sometimes a name is hard because the function does too much. If you can't name it concisely, that's a signal to split it.

Defaults and Options That Don't Pollute

Optional parameters are fine, but they should not create hidden branches. I prefer to pass explicit options rather than booleans that flip behavior.

# Bad: boolean flag changes behavior drastically
def format(data, pretty=False):
    if pretty:
        return json.dumps(data, indent=2)
    return json.dumps(data)

# Better: separate functions or an options object
import json

def format_compact(data):
    return json.dumps(data)

def format_pretty(data):
    return json.dumps(data, indent=2)

When you have many options, consider an options object or a configuration parameter. This keeps the signature stable and easy to extend.

Return Early, Return Often

Deeply nested conditionals are a sign of a function that's trying to do too much. I use guard clauses to handle edge cases first, then the main logic runs cleanly.

def get_discount(price, customer):
    if not customer.is_member:
        return 0
    if price < 100:
        return 0.05
    return 0.1

This linear flow is easier to follow than nested if-else blocks. It also makes it obvious what the function returns in each case.

The Compounding Effect

When you write clean functions, you build a vocabulary. Later, you can compose them like LEGO bricks. The whole system becomes greater than the sum of its parts because each function is predictable and testable.

For example, a payment flow might look like:

def process_payment(order, payment_method):
    amount = calculate_total(order)
    charge = charge_customer(payment_method, amount)
    send_receipt(order, charge)
    return charge

Each of those helper functions is simple, and the main function reads like a story.

Start Small, Refactor Later

You don't need to design perfectly upfront. Write the first version, then refactor. But keep the bar high: if you see a function that's hard to test, hard to name, or has too many responsibilities, break it down.

Clean function design is a habit. The more you do it, the more natural it becomes. And the payoff is real: less debugging, easier onboarding, and code that you actually enjoy reading six months later.

So next time you write a function, ask yourself: would I want to call this from another function? Would I want to unit test it? If the answer is no, redesign it. That small discipline compounds into a codebase that's a joy to work with.

Designing Functions That Compound: Small, Pure, and Composable

Code Atlas — Tue, 25 Aug 2026 08:00:34 +0000

The Power of Compounding Functions

When I first started writing code, I treated functions like isolated tasks: parse this input, format that output, save this record. Each function worked, but the codebase became a tangled mess of duplicated logic and hidden side effects. The turning point was learning to design functions that compound: small, pure, and composable units that build on each other like Lego bricks.

Compounding functions aren't just about reuse. They make reasoning easier, testing trivial, and refactoring safe. Here's how I approach it.

Start With Pure Functions

A pure function is one that always returns the same output for the same input and has no side effects (no I/O, no mutation of external state). Purity is the foundation of composability because you can trust it. If a function mutates something, you can't safely combine it with others without worrying about order and hidden dependencies.

Here's a simple example in JavaScript:

// impure: mutates the array
function addToCart(cart, item) {
  cart.push(item);
  return cart;
}

// pure: returns a new array
function addToCart(cart, item) {
  return [...cart, item];
}

The pure version can be used in any context without surprising the caller. It also makes testing trivial: no setup, no cleanup, just pass inputs and check outputs.

Make Functions Small and Single-Purpose

A function should do one thing and do it well. If you find yourself writing "and" in the function name (e.g., parseAndValidate), split it. Small functions are easier to reason about, test, and combine. They also tend to have clearer names, which is documentation in itself.

Consider this overblown function:

function processOrder(order) {
  // 30 lines of logic: validate, apply discount, calculate tax, format output
}

Break it down:

function validateOrder(order) { /* ... */ }
function applyDiscount(order, discount) { /* ... */ }
function calculateTax(subtotal) { /* ... */ }
function formatOrder(order) { /* ... */ }

n
Now each piece is testable in isolation and can be reused elsewhere. The composition happens at a higher level, like a pipeline.

Compose With Pipelines

Once you have small, pure functions, composition becomes natural. You can chain them, either manually or with a utility like pipe (available in lodash, Ramda, or you can write a tiny one yourself).

function pipe(...fns) {
  return (arg) => fns.reduce((acc, fn) => fn(acc), arg);
}

const processOrder = pipe(
  validateOrder,
  (order) => applyDiscount(order, order.coupon),
  calculateTax,
  formatOrder
);

This reads like a recipe. Each step is a function that takes the output of the previous one. If you need to add a step, you just insert another function. If a step fails, you know exactly where to look.

Design Functions With Data Flow in Mind

A common mistake is writing functions that require too much context. For example, a function that takes an entire object but only uses one property. Instead, design functions to accept exactly what they need and return what makes sense for the next step.

// less composable
function getFullName(user) {
  return `${user.firstName} ${user.lastName}`;
}

// more composable
function getFullName(firstName, lastName) {
  return `${firstName} ${lastName}`;
}

The second version can be used in map or reduce more easily, and it doesn't couple you to a specific data shape.

Embrace Currying for Partial Application

Currying lets you fix some arguments and get a new function for the rest. It's a powerful way to create specialized versions of generic functions, which then compose beautifully.

function multiply(a, b) {
  return a * b;
}

function curry2(fn) {
  return (a) => (b) => fn(a, b);
}

const multiplyCurried = curry2(multiply);
const double = multiplyCurried(2);
const triple = multiplyCurried(3);

[1, 2, 3].map(double); // [2, 4, 6]

Now double and triple are reusable, composable pieces. You can combine them with other functions without rewriting logic.

Testability as a Compounding Benefit

When functions are pure and small, testing becomes a joy. You write a test per function with a few inputs and expected outputs. No mocking, no setup. And because functions compose, you can test the composition as a whole by simply testing the pipeline with realistic inputs.

Here's a quick test for a pure function:

// test.js
test('calculateTax applies 10% rate', () => {
  expect(calculateTax(100)).toBe(10);
});

That's it. No database, no network, no global state. The confidence you get from these tests compounds: you can refactor the internals of a function without worrying about breaking the system, as long as the contract holds.

Avoid Over-Abstraction

Compounding doesn't mean abstracting everything into tiny pieces. Sometimes a function with a few lines is fine. The goal is to keep each unit at a level where it's obvious what it does. If you find yourself creating functions with names like doThing or process that just call other functions, you might be over-engineering.

A good heuristic: if a function is so short that it's just a wrapper, consider inlining it unless it provides a clear conceptual abstraction.

Refactoring Toward Compounding

If you have legacy code, start by identifying impure functions and converting them to pure ones. Then extract logical blocks into separate functions. Finally, compose them with a pipeline. Do it incrementally, one function at a time, and let tests guide you.

For example, I once had a massive handleRequest function that did validation, database access, and response formatting. I extracted the validation into a pure function, then the formatting, and left the side-effectful parts at the edges. The core logic became testable without a server.

The Compound Effect

Designing functions that compound isn't just a style choice. It's a discipline that pays off in every aspect of development: readability, maintainability, testing, and debugging. When each function is a small, pure, composable unit, your codebase becomes a toolkit of reliable building blocks. You start to see patterns, reuse becomes effortless, and new features feel like assembling existing pieces rather than writing fresh code from scratch.

Start small. Pick one function in your codebase that's doing too much, break it down, and compose it back together. The effect will surprise you, and it grows with every function you clean up. That's the compounding power of good design.

Designing Functions That Compound

Code Atlas — Fri, 21 Aug 2026 08:00:31 +0000

The Power of Small, Composable Functions

I've spent years refactoring messy codebases. The most common problem I see isn't lack of comments or poor naming-it's functions that try to do too much. A function that does one thing well is easy to test, debug, and reuse. But the real magic happens when you design functions that can be composed together, each one feeding into the next. This is what I call "compounding" function design.

Start with the Data Flow

Before writing a function, I ask: what data goes in, and what comes out? If the answer involves multiple unrelated transformations, I split it. For example, consider a function that fetches user data, filters active users, and formats their names:

// Bad: one function does everything
async function getActiveUserNames() {
  const response = await fetch('/api/users');
  const users = await response.json();
  return users
    .filter(u => u.active)
    .map(u => `${u.firstName} ${u.lastName}`);
}

This works, but it's hard to reuse any part. What if I need raw active users for another feature? I'd have to duplicate the fetch and filter logic.

Instead, I break it into three small functions:

async function fetchUsers() {
  const response = await fetch('/api/users');
  return response.json();
}

function filterActive(users) {
  return users.filter(u => u.active);
}

function formatNames(users) {
  return users.map(u => `${u.firstName} ${u.lastName}`);
}

Now I can combine them in different ways:

const activeUsers = filterActive(await fetchUsers());
const activeNames = formatNames(activeUsers);

Each function is pure (except the fetch), so I can test them in isolation. And I can reuse filterActive anywhere, not just after a fetch.

Make Functions Predictable

The best composable functions are pure: same input, same output, no side effects. This makes them predictable and easy to reason about. For instance, formatNames always returns the same array for the same input. It doesn't mutate the original array, doesn't log to console, doesn't touch global state.

If a function must have side effects (like fetchUsers), keep it at the edges of your system. Then pass the data through pure functions. This separation is the foundation of functional programming, but you can apply it even in imperative codebases.

Use Higher-Order Functions to Avoid Repetition

When you notice the same pattern of combining functions, abstract it. Higher-order functions (functions that take functions as arguments) are perfect for this. For example, I often need to apply a series of transformations to a list. Instead of writing a pipeline each time, I create a pipe helper:

function pipe(...fns) {
  return (input) => fns.reduce((acc, fn) => fn(acc), input);
}

const processUsers = pipe(filterActive, formatNames);

// Usage
const activeNames = processUsers(users);

Now processUsers is a new function that compounds the two smaller ones. If I later need to add a transformation, I just add it to the pipe call:

const processUsers = pipe(filterActive, sortByName, formatNames);

This is much cleaner than nesting function calls manually.

Design for Composition from the Start

When writing a new function, I ask: could someone else use this function as a building block? If so, I make sure:

The input and output are simple types (arrays, objects, primitives) rather than requiring specific context.
The function doesn't depend on external state unless absolutely necessary.
The name describes what it does, not why it's used (e.g., filterActive not getActiveUsersForDashboard).

This mindset shifts how you write code. Instead of solving a specific problem, you're building a toolbox of small, reliable pieces.

A Real-World Example

Let's say I'm building a report generator. I need to fetch sales data, group by region, compute totals, and format for CSV. Without composition, I'd write one giant function. With composition, I write:

const fetchSales = () => fetch('/api/sales').then(r => r.json());
const groupByRegion = sales => sales.reduce((acc, s) => {
  acc[s.region] = acc[s.region] || [];
  acc[s.region].push(s);
  return acc;
}, {});
const computeTotals = groups => Object.entries(groups).map(([region, items]) => ({
  region,
  total: items.reduce((sum, i) => sum + i.amount, 0)
}));
const toCSV = rows => rows.map(r => `${r.region},${r.total}`).join('\n');

const generateReport = pipe(fetchSales, groupByRegion, computeTotals, toCSV);

Each step is testable in isolation. I can test computeTotals with mock data without ever touching the network. And if the requirements change-say, I need to filter out low-value sales-I just insert a new function into the pipe.

The Payoff

Designing functions that compound isn't about being clever. It's about making your codebase more maintainable. When every function is a small, composable unit, debugging becomes easier (you isolate the broken step), testing becomes trivial (you test each piece), and adding features becomes safer (you add a new function without touching existing ones).

Start small: pick one function that does too much, break it into pieces, and see how they fit together. Once you feel the difference, you won't go back.

Logging Done Right: A Practical Guide

Code Atlas — Thu, 20 Aug 2026 00:00:38 +0000

Logging Done Right: A Practical Guide

Logging is one of those things we all do, but rarely do well. I've spent years sifting through tangled log files, and I've learned that a little discipline goes a long way. Here's how I approach logging in real projects.

Why Logging Matters

Logs are your app's black box. When something breaks in production, they're often the only clue you have. Good logs can turn a 3-hour debugging session into a 5-minute one. Bad logs are just noise that hides the signal.

The goal isn't to log more, it's to log better. Every log line should answer three questions: What happened? When did it happen? And what was the context?

Choose a Structured Format

Plain text logs are hard to parse, especially when you have multiple services. I always use structured logging, meaning each log entry is a JSON object. This makes it trivial to ship logs to a central aggregator like ELK or CloudWatch and query them programmatically.

Here's a simple example in Node.js using pino:

const pino = require('pino');
const logger = pino({
  level: process.env.LOG_LEVEL || 'info',
  base: { service: 'user-service' }
});

logger.info({ userId: 123, action: 'login' }, 'User logged in');

That outputs something like:

{"level":30,"time":1620000000000,"service":"user-service","userId":123,"action":"login","msg":"User logged in"}

Notice the context (userId, action) is in the structured fields, not buried in the message. That's key.

Log Levels: Use Them Wisely

Most loggers have these levels: debug, info, warn, error, fatal. I follow a simple rule:

debug: Detailed info for troubleshooting, usually noisy. Turn on only when needed.
info: High-level events that show the app is working (requests, cron runs, state changes).
warn: Something unexpected happened, but the app can continue. e.g., retrying a failed network call.
error: A failure that affects functionality, but the app can still run. e.g., a database query failed and we served a fallback.
fatal: The app can't continue, process is crashing.

Don't log everything at info. I see too many codebases where every function logs at info, making it impossible to filter for real issues. Reserve info for meaningful business events.

What to Log (and What Not to Log)

Log the essentials: request ID, user ID, service name, timestamps, and the outcome. Don't log sensitive data like passwords, tokens, or credit card numbers. Also, avoid logging large payloads or stack traces for expected errors.

Here's a pattern I use for request logging in Express:

app.use((req, res, next) => {
  const start = Date.now();
  res.on('finish', () => {
    logger.info({
      method: req.method,
      url: req.url,
      status: res.statusCode,
      duration: Date.now() - start,
      requestId: req.headers['x-request-id'] || crypto.randomUUID()
    }, 'Request completed');
  });
  next();
});

That single line gives you a full audit trail of every request, including latency and status.

Error Logging: Include the Stack Trace and Context

When logging errors, always include the stack trace and as much context as possible. The error object in Node.js has a stack property, but you need to pass it explicitly:

try {
  await db.query(...);
} catch (err) {
  logger.error({
    err,
    userId: req.user.id,
    query: 'SELECT * FROM users WHERE id = ?'
  }, 'Database query failed');
}

Notice I pass the err object itself. Pino (and others) will serialize its stack and message automatically. Never log err.message only, you'll lose the stack trace.

Don't Log in Loops

Logging inside a tight loop can kill performance and flood your log storage. Instead, aggregate. For example, if you're processing 10,000 items, log one summary at the end with counts and failures:

let successCount = 0;
let failureCount = 0;

for (const item of items) {
  try {
    await process(item);
    successCount++;
  } catch {
    failureCount++;
  }
}

logger.info({ total: items.length, successCount, failureCount }, 'Batch processing complete');

If you need per-item logs, use debug level, not info.

Correlation IDs: Trace a Request Across Services

In a microservices architecture, a single user request may hit multiple services. Without a correlation ID, you can't piece together the full journey. Generate a UUID at the entry point (e.g., API gateway) and pass it via headers to all downstream services.

In your logger, always include that ID as a field. Then, when you search logs, you can filter by that ID and see every log line from all services in chronological order.

Log Rotation and Retention

Logs grow fast. Make sure you have a rotation strategy. Most loggers support rotation by size or time. In production, I typically keep logs for 30 days, but adjust based on compliance needs. If you're using a cloud logger, set up lifecycle rules to move old logs to cheaper storage.

Test Your Logging

Logging is code, so test it. I've written unit tests that verify certain actions produce log entries with the expected level and context. This catches silly mistakes like logging at the wrong level or missing a field.

Final Thoughts

Good logging is an investment. It takes a bit of upfront effort, but it pays off every time something breaks. Start by adopting structured logging, use levels correctly, and always include context. Your future self (and your on-call rotation) will thank you.

I still find myself improving my logging habits on every project. It's a craft, and like any craft, practice makes perfect.