DEV Community: Code Atlas

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.

Naming Things Without Pain

Code Atlas — Tue, 18 Aug 2026 00:01:05 +0000

The Real Problem With Naming

We've all been there: staring at a blank line, trying to come up with a name for a variable, function, or class. It feels like the hardest part of coding, and sometimes it is. But naming isn't about creativity or finding the perfect word. It's about clear communication. When you name something well, the code reads like a story. When you name it poorly, you force the next developer (or yourself in six months) to decode your intentions.

Start With the Why

Before you write a single name, ask yourself: what does this thing do? Not what it is, but what it does. For functions, that's easy: the name should be a verb phrase. For variables, think about the role the value plays, not the type.

# Bad
items = [1, 2, 3]

def process(data):
    total = 0
    for d in data:
        total += d
    return total

# Good
prices = [19.99, 5.49, 3.00]

def calculate_total(prices):
    total = 0
    for price in prices:
        total += price
    return total

The second version tells you what the data means and what the function accomplishes. You can read it without tracing through the logic.

Use Intent-Revealing Names

Names should answer questions, not raise them. Avoid generic terms like data, info, temp, or thing. They don't reveal anything. Instead, be specific about the domain.

// Bad
const d = new Date();
const t = d.getTime();

// Good
const currentTime = new Date();
const timestamp = currentTime.getTime();

Even better, if you're working in a specific domain, use its vocabulary. If you're building an e-commerce app, use cart, checkout, invoice. If you're doing image processing, use pixel, canvas, filter. The domain language is your friend.

Keep It Short, But Not Too Short

Short names are great for local variables that are used immediately. But they're terrible for things that live across many lines or are passed around. A good rule of thumb: the larger the scope, the longer the name.

// Bad: too short for a field
private int n;

// Good: clear and descriptive
private int numberOfRetries;

But don't go overboard. numberOfItemsInTheShoppingCart is a mouthful. cartItemCount is perfect. Aim for 2-3 words that capture the essence.

Consistency Is King

Once you pick a naming convention, stick to it. If you use getUser in one place, don't use fetchUser in another. If you use isReady for booleans, don't switch to ready somewhere else. Consistency reduces cognitive load. The reader doesn't have to remember exceptions.

For booleans, prefix with is, has, can, or should. For functions that return a value, use verbs like get, calculate, find. For functions that perform an action, use set, save, delete, send.

# Consistent boolean naming
is_active = True
has_permission = False
can_edit = True

Avoid Abbreviations and Acronyms

Unless it's a widely accepted standard like HTML or API, avoid abbreviating. usr instead of user saves two characters but costs clarity. Acronyms like TMP or CNT are even worse. Write it out. Your editor has autocomplete.

When You Can't Think of a Name

If you're stuck, it's often a sign that the code is doing too much. A function that's hard to name might be doing two things. Split it. A variable that's hard to name might be storing something unclear. Rethink the logic.

Another trick: write a comment describing what the thing does, then turn that comment into a name. For example, "this list contains all the IDs of users who have unread notifications" becomes unreadNotificationUserIds. That's a name with a story.

The Hardest Names: Booleans and Functions

Booleans are tricky because they represent a state. Use positive, clear predicates. Instead of notFinished, use isComplete. Instead of noErrors, use hasErrors. Positive names are easier to reason about.

For functions, the name should describe the result, not the implementation. getUser is better than loadUserFromDatabase because the caller doesn't care where it comes from. But if the function has side effects, make that obvious: saveUser or deleteUser are clear.

Refactor Names as You Go

Naming is not a one-time decision. As your code evolves, names should evolve too. If you realize a variable is misnamed, change it. Don't feel bad about renaming things. It's part of the craft. Most IDEs make renaming easy and safe.

Final Thoughts

Naming is about empathy for the reader. You're writing code for humans first, machines second. A good name saves minutes of debugging and hours of confusion. It's not about being clever; it's about being clear. Next time you're stuck, remember: if you can't name it, you probably don't understand it. And that's the name of the game.

A Simple Git Workflow That Scales for Small Teams

Code Atlas — Fri, 14 Aug 2026 08:00:17 +0000

The Problem with Git Chaos

Small teams often start with everyone committing directly to main. It works until it doesn't: broken builds, merge conflicts, and the dreaded "who wrote this?" blame game. You don't need a heavyweight process like GitFlow, but you do need a lightweight workflow that keeps the shared branch stable and reviews painless.

Here's a workflow I've used on teams of 2 to 10 people. It's simple, explicit, and handles most real-world scenarios without ceremony.

The Core Rules

main is always deployable. No direct pushes. Ever.
Every change goes through a feature branch and a pull request.
Branch names describe intent: feature/, fix/, chore/.
Keep branches short-lived (max a couple of days).
Rebase before merging, but don't rewrite shared history.

That's it. The rest is mechanics.

Setting Up the Basics

First, protect main on your Git host (GitHub, GitLab, Bitbucket). Require at least one approval and passing CI. This is non-negotiable.

Next, establish a consistent branching convention. I like:

feature/add-login-page
fix/typo-in-footer
chore/update-dependencies

Use slashes, not dots. It keeps things tidy in your branch list.

The Daily Loop

Here's the routine each developer follows, step by step.

1. Start from a fresh `main`

git checkout main
git pull origin main
git checkout -b feature/my-change

Always pull before branching. This reduces merge conflicts later.

2. Make small, focused commits

Commit often with clear messages. Use the imperative mood: "Add validation", not "added stuff".

git add .
git commit -m "Add email validation to signup form"

3. Push and open a PR early

Don't wait until the feature is perfect. Push a branch with a single commit and open a draft PR. This gives your team visibility and lets you ask for early feedback.

git push -u origin feature/my-change

4. Keep your branch up to date

While you work, main moves. Rebase your branch onto the latest main regularly. This keeps the history linear and avoids messy merge commits.

git fetch origin
git rebase origin/main

If you hit conflicts, resolve them, then continue:

git add .
git rebase --continue

5. Merge with a squash

When the PR is approved and CI passes, merge using squash and merge. This collapses all your tiny commits into one clean commit on main.

# On GitHub/GitLab, click the squash merge button
# Or locally:
git checkout main
git pull origin main
git merge --squash feature/my-change
git commit -m "Add login page"
git push origin main
git branch -d feature/my-change

Squashing keeps main history readable. Each commit is a complete, working unit.

Handling Common Situations

Hotfixes

A hotfix is just a branch, but it gets priority. Create fix/critical-bug from main, fix, test, and merge immediately. Don't wait for other features.

Large features

If a feature takes longer than a few days, consider merging it behind a feature flag. This keeps the branch from drifting too far from main. You can also split it into smaller PRs that each merge into main without breaking anything.

Multiple people on the same feature

Rarely needed, but if two people must work on the same feature, have them share a branch. They can push to the same remote branch and coordinate. But in most cases, split the work into separate branches.

Why This Works

Stable main: No one can break the shared branch accidentally.
Code review: Every change gets a second pair of eyes.
Clean history: Squash merging keeps main readable.
Low overhead: No complex rules, no release branches, no backporting.

You can adopt this workflow in an afternoon. It doesn't require new tools or training, just discipline. Once your team gets used to it, you'll wonder how you ever worked without it.

Final Tips

Write good PR descriptions. Include what and why, not just how.
Use templates for PRs if your Git host supports them.
Don't be afraid to comment on your own PR. It helps reviewers.
If a rebase gets messy, git rebase --abort and try again. You can always squash at the end.

This workflow isn't revolutionary. It's just solid practice, scaled down to what small teams actually need. Give it a try, and adjust the details to fit your team's rhythm. The goal is to spend less time fighting Git and more time shipping software.

Naming Things Without Pain

Code Atlas — Wed, 12 Aug 2026 16:07:00 +0000

The Real Problem With Naming

We've all been there. You write a function, pause, and stare at the cursor for two minutes trying to decide between getUserData, fetchUser, or loadUser. Naming is hard because names carry intent, and intent is fuzzy. But the pain isn't inevitable. It's a symptom of unclear design or overthinking. Here's how I approach naming in my daily work, without the agony.

Start With the Why, Not the What

Before naming, ask: what is this thing for? A good name describes behavior, not implementation. getUser tells me what it returns. getUserFromApi tells me where it comes from, which is an implementation detail. If I later switch from API to cache, the name lies. Prefer getUser and let the caller not care about the source.

For booleans, use is, has, can, or should. isActive, hasPermission, canEdit. Avoid negatives like notDisabled because they double the cognitive load. isEnabled is simpler than isNotDisabled.

Use the Right Level of Abstraction

Naming pain often comes from mixing levels. If you have a saveUser function that also validates and sends an email, the name is too narrow. Rename it to registerUser or split it. Names should match the scope of what the code does. If you can't find a name that fits, your function probably does too much.

Consistency Beats Creativity

Pick a convention and stick to it. If your codebase uses get for simple getters, don't name a function retrieve. If you use create for object creation, don't use make. Consistency reduces surprise. When I see getUser in one file, I expect getOrder in another, not fetchOrder.

For variables, be consistent with units and formats. timeoutMs and timeoutSeconds are clearer than timeout and delay. If you have a userList, don't call another usersArray. Choose one plural form.

The Two-Second Rule

If you have to think about a name for more than a few seconds, you're probably missing a concept. Step back and ask: is there a term from the domain that fits? For example, instead of itemsThatAreOverdue, call it overdueItems. Instead of checkIfUserCanAccess, call it canUserAccess. Domain language is often shorter and clearer.

Refactor Names Without Guilt

Naming is not a one-time decision. It's okay to rename later when you understand the code better. In fact, that's a sign of growth. I rename constantly during code review. If a colleague suggests a better name, I take it. It's not a criticism of my intelligence, it's a shared effort to make the code clearer.

Practical Heuristics I Use

Functions: verb + noun. saveReport, sendNotification. Avoid doStuff or handleClick unless it's a callback.
Classes: noun. User, OrderProcessor, PaymentService. Avoid verbs like Manage unless it's a manager pattern.
Variables: nouns or adjectives. count, isReady, totalPrice. Avoid data, info, temp unless truly temporary.
Constants: uppercase with underscores. MAX_RETRIES, DEFAULT_TIMEOUT.
Booleans: ask a yes/no question. isLoaded, hasError, canSend.

When You're Stuck: Fake It

If you can't find a name, write a comment describing what the function does, then extract the main verb and noun. For example, comment says "this function checks if the user has enough balance to purchase an item". Name: canUserPurchase. If that's too long, userCanPurchase works. If it's still awkward, your function is probably doing too much.

A Simple Process for Naming

Write the code first, even with a placeholder name like foo. Get the logic right.
After it works, read it and ask: what does this do? Write a one-line answer.
Turn that answer into a name. Use the heuristics above.
If the name is longer than 3-4 words, consider splitting the function.

This process removes the pressure of naming upfront. You name after you understand, not before.

Final Thoughts

Naming is a skill, not a talent. The more you practice, the faster it gets. I still struggle with names, but now I have a toolkit. I ask why, I stay consistent, and I rename freely. The pain is mostly gone because I stopped trying to find the perfect name on the first try. Instead, I find a good enough name, and I improve it when the code tells me more.

Remember: a name is a contract. It should communicate intent clearly, not impress with cleverness. When in doubt, choose the boring, obvious name. Your future self and your teammates will thank you.

Error Handling Patterns That Actually Scale

Code Atlas — Mon, 10 Aug 2026 16:06:47 +0000

Start with the fundamentals

Every codebase eventually faces the question: how do we handle errors consistently? The answer isn't a silver bullet, but a set of patterns that fit different contexts. I've seen teams over-engineer this, and I've seen teams ignore it until production screams. Here's what works.

The classic: try/catch

JavaScript's try/catch is the baseline. It's imperative, local, and easy to reason about for small blocks.

try {
  const data = JSON.parse(raw);
  process(data);
} catch (err) {
  console.error('Parsing failed', err);
  fallback();
}

But it has a problem: it catches everything in the block, including bugs you didn't anticipate. Mixing expected failures (like invalid input) with unexpected ones (like a typo in your code) makes debugging harder. A common improvement is to rethrow unexpected errors:

try {
  riskyOperation();
} catch (err) {
  if (err instanceof ValidationError) {
    handleValidation(err);
  } else {
    throw err; // let it bubble up
  }
}

That's better, but it gets verbose fast. Which leads to the next pattern.

Result objects: no surprises

Instead of throwing, return a value that explicitly represents success or failure. This is common in Go, Rust, and increasingly in TypeScript with discriminated unions.

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 (e) {
    return { ok: false, error: e as Error };
  }
}

const result = parseJson(input);
if (!result.ok) {
  console.error(result.error);
  return;
}
console.log(result.value);

The caller must check ok before using value. That's a feature: errors become part of the function's contract. No hidden throw, no forgotten catch. The downside is verbosity, but you can mitigate with helper functions or a library like neverthrow (well-known, but you can roll your own).

The Either monad: functional flavor

If you're comfortable with functional programming, Either is a common abstraction. It's like a result object but with more combinators.

// Simplified Either
type Either<L, R> = { kind: 'left'; left: L } | { kind: 'right'; right: R };

function divide(a: number, b: number): Either<string, number> {
  if (b === 0) return { kind: 'left', left: 'Division by zero' };
  return { kind: 'right', right: a / b };
}

const outcome = divide(10, 0);
if (outcome.kind === 'left') {
  console.error(outcome.left);
} else {
  console.log(outcome.right);
}

This pattern shines in pipelines where you chain operations and want to short-circuit on the first error without nested ifs. But it requires discipline and can be overkill for small apps.

Async errors: the promise way

For asynchronous code, async/await with try/catch is standard. However, a common mistake is wrapping every await in its own try/catch, leading to deeply nested code. Instead, group related operations and handle errors at the boundary.

async function fetchUser(id) {
  try {
    const response = await fetch(`/users/${id}`);
    if (!response.ok) throw new Error(`HTTP ${response.status}`);
    return await response.json();
  } catch (err) {
    // Log and rethrow a domain-specific error
    throw new Error(`Failed to fetch user ${id}: ${err.message}`);
  }
}

For multiple independent async calls, Promise.allSettled is your friend. It doesn't throw on the first rejection; it returns results for all promises.

const results = await Promise.allSettled([fetchA(), fetchB(), fetchC()]);
const successful = results.filter(r => r.status === 'fulfilled');
const failed = results.filter(r => r.status === 'rejected');

Global error handling

No matter how careful you are, some errors slip through. At the application level, set up global handlers to log and recover gracefully.

In browsers:

window.addEventListener('unhandledrejection', event => {
  console.error('Unhandled promise rejection', event.reason);
  // optionally show a user-friendly message
});

In Node.js:

process.on('uncaughtException', err => {
  console.error('Uncaught exception', err);
  // cleanup and exit or restart
  process.exit(1);
});

But be careful: uncaughtException should be a last resort. It can leave your app in an inconsistent state. Prefer handling errors as close to the source as possible.

Practical advice

Be explicit: Prefer result objects or discriminated unions for expected failures (validation, network errors). Use exceptions for truly unexpected bugs.
Don't swallow errors: An empty catch {} is a code smell. At least log.
Wrap third-party errors: Convert library errors into your own domain errors to keep your codebase decoupled.
Use a consistent error type: Create a base AppError class with properties like code, message, details. This makes error handling uniform across your app.

class AppError extends Error {
  constructor(code, message, details = {}) {
    super(message);
    this.code = code;
    this.details = details;
  }
}

Conclusion

There's no one-size-fits-all. Start with try/catch for simple cases, adopt result objects for functions where failure is a normal outcome, and use Promise.allSettled for parallel async work. The key is consistency. Pick a pattern for a given context and stick to it. Your future self (and your team) will thank you.

For deeper reading, the MDN guide on error handling is a solid reference.

Refactoring Safely: A Step-by-Step Guide

Code Atlas — Fri, 07 Aug 2026 00:01:55 +0000

Refactoring Safely: A Step-by-Step Guide

Refactoring is like renovating a house: you want to improve the structure without breaking the plumbing. Done carelessly, it can introduce bugs and chaos. Done methodically, it makes your code cleaner and more maintainable. Here's how I approach refactoring safely, step by step.

1. Understand the Current Behavior

Before touching anything, I need to know what the code is supposed to do. I read the relevant tests, documentation, and comments. If there are no tests, I write them first. This might seem like extra work, but it's the safety net that lets me refactor with confidence.

// Example: a function that needs refactoring
function calculateTotal(items) {
  let total = 0;
  for (let i = 0; i < items.length; i++) {
    total += items[i].price * items[i].quantity;
  }
  return total;
}

I write tests that cover normal cases, edge cases, and error cases. The tests should pass before I change anything.

2. Make Small, Atomic Changes

I never try to refactor everything at once. I break the work into small, focused steps. Each step should leave the code in a working state. This way, if something breaks, I know exactly which change caused it.

For the calculateTotal function, I might first extract the inner calculation into a helper function:

function lineTotal(item) {
  return item.price * item.quantity;
}

function calculateTotal(items) {
  let total = 0;
  for (let i = 0; i < items.length; i++) {
    total += lineTotal(items[i]);
  }
  return total;
}

Run the tests. They should still pass. Then I can replace the loop with reduce:

function calculateTotal(items) {
  return items.reduce((sum, item) => sum + lineTotal(item), 0);
}

Again, run tests. Each step is verifiable.

3. Run Tests Frequently

I run the test suite after every small change. It's tempting to make several changes and then test, but that defeats the purpose. Frequent testing means when a test fails, I know exactly what I just did. If I'm using a watch mode, even better.

If a test fails, I revert the last change and rethink. There's no shame in reverting; it's part of the process.

4. Use Version Control as a Safety Net

Before starting, I commit the current state. Then I create a new branch for the refactor. Each successful step gets a commit. This gives me checkpoints to roll back to if needed. It also lets me compare before and after easily.

git checkout -b refactor-calculate-total
git commit -m "Add tests for calculateTotal"
# ... make changes ...
git commit -m "Extract lineTotal helper"

5. Keep Behavior Identical

Refactoring is not about adding features or fixing bugs. It's about improving the internal structure while keeping external behavior the same. If I notice a bug during refactoring, I stop and fix it separately, with its own test. Mixing concerns makes it hard to isolate issues.

6. Leverage the Compiler and Linter

If you're using a statically typed language, the compiler is your friend. It catches type mismatches and missing references. Linters can catch style issues, but they can also catch common mistakes. I run them after each change to catch obvious problems early.

7. Refactor in Layers

Big refactors often span multiple layers: database, API, business logic, UI. I go top-down or bottom-up, but always one layer at a time. For example, I might refactor a service function first, then update the controller that calls it, then the UI. Each layer should be independently testable.

8. Use Automated Refactoring Tools When Possible

IDEs like IntelliJ, VS Code, and Eclipse have built-in refactoring tools for renaming, extracting methods, and more. They handle the mechanical parts safely, reducing human error. I use them when available, but I still review the changes they make.

9. Don't Be Afraid to Rewrite

Sometimes the code is so tangled that incremental refactoring is impractical. In that case, I might rewrite the module from scratch, but I still follow the same principles: understand the behavior, write tests, and build the new version piece by piece.

10. Review and Clean Up

After the refactor, I review the diff. I look for any leftover dead code, unused imports, or awkward naming. I run the full test suite one more time. Then I commit and merge.

Conclusion

Refactoring safely is about discipline: small steps, constant testing, and version control. It's not glamorous, but it prevents the chaos that comes from big-bang rewrites. The next time you're tempted to "just fix it quickly," remember: slow and steady wins the race. Your future self will thank you.

Testing Basics That Actually Pay Off

Code Atlas — Wed, 05 Aug 2026 08:00:29 +0000

Start With the Tests That Hurt

I used to skip testing because it felt like overhead. Then a bug in a payment calculation shipped to production and I spent a weekend fixing it. That's when I stopped treating tests as a chore and started treating them as a safety net.

You don't need a 100% coverage badge or a complex test pyramid. You need a few testing habits that give you the most return for the least effort. Here's what I've found works.

Test the Critical Path First

Every codebase has a handful of functions that, if they break, cost you money or users. For me it was the pricing logic. For you it might be authentication, data validation, or the API endpoint that writes to the database.

Write tests for those first. Not the utility functions that just format a date. The stuff that really matters.

# Example: testing a discount calculation
def test_discount_applies_when_over_threshold():
    assert calculate_final_price(120, discount_rate=0.1) == 108

def test_discount_does_not_apply_below_threshold():
    assert calculate_final_price(80, discount_rate=0.1) == 80

These tests are simple, but they force you to think about edge cases like boundary values. And when someone later changes the threshold, a test will remind you.

Use the Right Kind of Test for the Job

Unit tests are great for isolated logic. Integration tests are better for the glue between modules. End-to-end tests are slow and brittle, so use them sparingly.

A common mistake is writing too many end-to-end tests that click through a browser. They break every time the UI changes and slow down your CI. Instead, rely on unit tests for logic and a few integration tests for the critical flows.

// Integration test for a user signup flow
const response = await request(app).post('/api/signup').send({
  email: 'test@example.com',
  password: 'password123'
});

expect(response.status).toBe(201);
expect(response.body.user.email).toBe('test@example.com');

That one integration test covers the route, the validation, and the database write. It's worth more than ten unit tests that mock everything.

Make Tests Readable and Maintainable

Tests that are hard to read get deleted. Write tests like you write documentation. Use descriptive test names, keep them short, and avoid excessive setup.

If you need to set up a complex object in every test, create a factory function. It saves you from repeating the same code and makes it obvious what's different in each test.

def make_user(role="basic", verified=False):
    return {"id": 1, "role": role, "verified": verified}

def test_admin_user_can_delete_posts():
    user = make_user(role="admin", verified=True)
    assert can_delete_post(user) is True

This pattern makes your test suite a pleasure to read, and it encourages you to add more tests because it's cheap.

Run Tests Automatically, Not Manually

If you have to remember to run tests, you'll forget. Set up a pre-commit hook or a CI pipeline that runs your tests on every push. The feedback loop should be fast and automatic.

I use a simple script that runs the test suite before every commit. It takes five seconds and saves me from pushing broken code.

# pre-commit hook (simplified)
npm test

Once it's automatic, you'll stop thinking about testing as a separate activity. It's just part of shipping code.

Test the Fix, Not the Symptom

When you find a bug, write a test that reproduces it before you fix it. That test should fail, then you fix the code, and the test passes. This is called regression testing, and it's the most valuable testing habit I've adopted.

It forces you to understand the bug deeply and ensures it never comes back. Plus, it's satisfying to see the red-to-green transition.

Keep Tests Fast

Slow tests become skipped tests. Keep your test suite fast by using in-memory databases, mocking external services, and avoiding unnecessary I/O.

If a test takes more than a few seconds, it's too slow. Break it into smaller pieces or mock the slow parts. Your future self will thank you when you can run the whole suite in under a minute.

Don't Aim for 100% Coverage

Coverage percentage is a vanity metric. A 100% covered codebase can still have bugs in the logic, and a 50% covered one can be rock solid if the critical paths are tested.

Instead of chasing a number, focus on testing the code that scares you. If you're nervous about changing a function, it needs a test. If you're confident, maybe it's fine as is.

Start Small and Build the Habit

You don't need to test everything today. Pick one critical function and write a test for it. Then another. Soon you'll have a suite that gives you confidence to refactor, add features, and sleep better at night.

Testing isn't glamorous, but it's the difference between shipping with fear and shipping with confidence. And once you feel that difference, you'll never go back.

Refactoring Safely: A Step-by-Step Guide

Code Atlas — Mon, 03 Aug 2026 08:01:10 +0000

Start with a Safety Net

Refactoring is like changing the tires on a moving car. You want to improve the code's structure without changing its behavior. The first rule is: never refactor without tests. If your codebase has no tests, write some before touching anything. Focus on the critical paths and edge cases. Even a few smoke tests give you confidence.

# Example: a simple function to test before refactoring
def calculate_total(items):
    total = 0
    for item in items:
        total += item['price'] * item['quantity']
    return total

# Test
assert calculate_total([{'price': 2, 'quantity': 3}]) == 6

Make Small, Atomic Changes

Break your refactoring into tiny steps. Each step should keep the code compiling and tests passing. If you try to do too much at once, you'll lose track of what broke. For example, rename a variable, run tests, then move a function, run tests again. This is the essence of the "strangler fig" approach: slowly replace parts without a big bang.

// Before: messy function
function processOrder(order) {
  let total = 0;
  for (let i = 0; i < order.items.length; i++) {
    total += order.items[i].price * order.items[i].qty;
  }
  return total;
}

// Step 1: rename qty to quantity (just one change)
function processOrder(order) {
  let total = 0;
  for (let i = 0; i < order.items.length; i++) {
    total += order.items[i].price * order.items[i].quantity;
  }
  return total;
}

Use the Compiler and Linters as Your Allies

Modern IDEs and compilers can catch many issues before you run tests. After each change, run the build or type checker. If you're using TypeScript, a type error might point to a subtle bug. Linters can enforce style consistency as you go. Don't ignore warnings; they often highlight code that will bite you later.

Keep Behavior Identical: The Golden Rule

Every refactoring should preserve observable behavior. If you're extracting a method, ensure it returns the same values for the same inputs. If you're changing a loop to a list comprehension, test it with edge cases: empty lists, negative numbers, duplicate entries. A quick way to verify is to run the old and new versions side by side on sample data.

# Old version
def get_even_numbers(numbers):
    result = []
    for n in numbers:
        if n % 2 == 0:
            result.append(n)
    return result

# New version
def get_even_numbers(numbers):
    return [n for n in numbers if n % 2 == 0]

# Verify
assert get_even_numbers([1,2,3,4]) == [2,4]

Commit Often, Revert Easily

Make a commit after each successful step. This gives you a checkpoint to roll back to if something goes wrong later. Write clear commit messages like "Extract method for price calculation" so you can find the exact change. If a test fails and you can't fix it quickly, revert to the last good commit and try a different approach.

Use Feature Flags for Large Refactors

If you need to refactor a core module that affects many parts of the system, consider wrapping the new implementation behind a feature flag. This way, you can ship the new code to a small subset of users, monitor for issues, and then gradually roll it out. This is especially useful for performance-critical code or when you can't have a full test suite.

// Using a simple flag
const useNewParser = process.env.USE_NEW_PARSER === 'true';

function parse(data) {
  if (useNewParser) {
    return parseNew(data);
  }
  return parseOld(data);
}

Review Your Own Diff

Before merging, review the diff as if you were a stranger. Look for places where you might have accidentally changed behavior. Check for off-by-one errors, reversed conditions, or missing null checks. This self-review often catches what tests miss.

Practice on a Side Project

If you're new to refactoring, practice on a small personal project first. The skills transfer directly to work, but the stakes are lower. You'll learn how to break down complex changes and trust your safety net.

Conclusion

Refactoring safely is about discipline: small steps, constant testing, and frequent commits. It's not about being perfect but about being able to revert and try again. Over time, you'll develop an instinct for what changes are safe and what needs extra caution. The result is cleaner code and a team that isn't afraid to improve the codebase.

Remember: if it hurts, do it more often. The more you refactor, the easier it becomes.

A Git Workflow for Small Teams

Code Atlas — Thu, 30 Jul 2026 16:01:46 +0000

Keep It Simple

Small teams don't need the complexity of Git Flow or the overhead of trunk-based development with feature flags. You need something that gets out of your way. Here's a workflow that has worked for my teams: main + short-lived feature branches.

The Core Rules

One permanent branch: main. It's always deployable. Protect it with branch rules: require pull request reviews, status checks, and no direct pushes.
Feature branches: Branch off main, name them feature/short-description or just username/description. Keep them short-lived (1-2 days max).
Pull requests: Every branch merges via PR. This triggers CI, code review, and a final sanity check.
Rebase before merge: Keep history linear. Rebase your feature branch onto main before merging.

Example Workflow

# Start a new feature
git checkout main
git pull
git checkout -b feature/add-login

# Work, commit, push
git add .
git commit -m "Add login form"
git push -u origin feature/add-login

# Open a PR on GitHub/GitLab/Bitbucket
# After review, rebase and merge
git checkout main
git pull
git rebase main feature/add-login  # or: git checkout feature/add-login && git rebase main
git checkout main
git merge feature/add-login
git push

Why This Works

No long-lived branches: Avoids the pain of merge conflicts from branches that drifted too far.
Simple mental model: Developers only need to think about main and their current branch.
Easy rollbacks: If something breaks, revert the merge commit on main. Since history is linear, reverts are clean.
CI/CD friendly: Every push to main can trigger deployment. No staging branches needed unless your deployment process requires them.

Hotfixes

For urgent fixes, branch off main, fix, PR, merge. Then rebase any in-progress feature branches onto the new main.

git checkout main
git pull
git checkout -b hotfix/critical-bug
# fix, commit, push, PR
# after merge, rebase your feature branch
git checkout feature/in-progress
git rebase main

Avoiding Common Pitfalls

Don't merge main into your feature branch: Instead, rebase. Merging creates unnecessary merge commits and makes history messy.
Keep branches small: If a feature takes more than two days, split it. Large branches are hard to review and merge.
Communicate: Let the team know when you're about to rebase or force-push (though with rebase before merge, force-pushing shouldn't be needed if you never push a rebased branch).

When to Level Up

This simple workflow can take a team of 2-10 developers a long way. When you start facing frequent conflicts, release coordination issues, or need multiple environments, consider adding:

A develop branch for integration testing (but beware: it adds complexity).
Release branches for versioning.
Feature flags to merge incomplete features into main without deploying them.

But for most small teams, the overhead isn't worth it. Start simple, and only add complexity when the pain is real.

Summary

One permanent branch: main.
Short-lived feature branches, rebased before merge.
PR-based code review and CI.
Hotfixes follow the same pattern.

This workflow keeps your Git history clean, your deployments predictable, and your team focused on building features instead of fighting with Git.

A Simple Git Workflow for Small Teams

Code Atlas — Wed, 29 Jul 2026 00:01:10 +0000

Introduction

Small teams don't need GitFlow or other complex branching models. They need a workflow that's easy to understand, quick to execute, and minimizes merge headaches. Here's a practical workflow I've used with teams of 2-8 developers.

The Core Idea: Main and Short-Lived Feature Branches

We keep it simple with one long-lived branch (main) and short-lived feature branches. Every change starts from main and is merged back as soon as it's ready.

git checkout main
git pull
git checkout -b feature/my-feature

Branch Naming Convention

Use a consistent prefix to keep branches organized:

feature/ for new features
fix/ for bug fixes
chore/ for maintenance tasks

Example: feature/user-authentication, fix/login-error

The Workflow Step by Step

1. Start from an Up-to-Date Main

Before creating a branch, make sure your local main is up to date:

git checkout main
git pull --rebase

2. Create a Feature Branch

git checkout -b feature/awesome-feature

3. Make Small, Frequent Commits

Commit early and often. Each commit should represent a logical unit of work.

git add .
git commit -m "Add user model with email validation"

4. Push and Open a Pull Request

Even if the branch isn't finished, pushing early allows others to see your progress.

git push -u origin feature/awesome-feature

Then open a PR against main. Keep PRs small (under 400 lines if possible).

5. Keep Your Branch Updated

If main moves forward, rebase your branch to avoid conflicts later:

git checkout feature/awesome-feature
git rebase main
# resolve conflicts if any
git push --force-with-lease

--force-with-lease is safer than --force because it prevents overwriting others' work.

6. Code Review

At least one other team member reviews the PR. Look for logic errors, readability, and test coverage.

7. Merge via Squash Merge

When the PR is approved, use squash merge to keep main history clean:

git checkout main
git pull
git merge --squash feature/awesome-feature
git commit -m "Add awesome feature"

Or use the GitHub/GitLab squash merge button. This collapses all your feature branch commits into one commit on main.

8. Delete the Feature Branch

After merging, delete the branch both locally and remotely:

git branch -d feature/awesome-feature
git push origin --delete feature/awesome-feature

Handling Hotfixes

For urgent fixes, create a branch directly from main:

git checkout main
git pull
git checkout -b fix/critical-bug
# fix, commit, push, PR, squash merge

No need for separate release branches unless you're maintaining multiple versions.

Why This Works for Small Teams

Simplicity: Only two types of branches (main and feature).
Speed: No long-lived release branches. Features go out as soon as they're ready.
Minimal Conflicts: Frequent rebasing and small PRs reduce merge conflicts.
Clean History: Squash merging keeps main linear and readable.

Common Pitfalls

Long-lived branches: If a branch lives more than a day or two, rebase often.
Large PRs: Break them down. A 1000-line PR is harder to review and more likely to have conflicts.
Force pushing: Use --force-with-lease and communicate with your team before force pushing shared branches.

Conclusion

This workflow is battle-tested for small teams. It's not fancy, but it's effective. Start with this, and only add complexity when you genuinely need it. Your team will thank you for keeping things simple.

How to Refactor Code Safely: A Step-by-Step Guide

Code Atlas — Mon, 27 Jul 2026 08:00:16 +0000

Introduction

Refactoring is the process of improving the internal structure of code without changing its external behavior. It's essential for keeping codebases maintainable, but it can be risky if done carelessly. In this article, I'll share a practical, step-by-step approach to refactoring safely, based on my experience working on large production systems.

Step 1: Understand the Code Before Changing It

Before you touch a single line, make sure you understand what the code does. Read the existing tests, if any. If there are no tests, write some. Even a simple smoke test can catch regressions.

// Example: a function that calculates discount
function calculateDiscount(price, type) {
  // ... complex logic
}

// Write a simple test before refactoring
console.assert(calculateDiscount(100, 'standard') === 10, 'Standard discount should be 10%');

Step 2: Have a Safety Net (Tests)

Ideally, your codebase has automated tests. If not, invest time in adding them. Focus on the area you plan to refactor. Use property-based testing or golden master tests if the logic is complex.

import unittest

class TestDiscount(unittest.TestCase):
    def test_standard_discount(self):
        self.assertEqual(calculate_discount(100, 'standard'), 10)

Run the tests and ensure they pass before you start.

Step 3: Make Small, Incremental Changes

Don't rewrite everything at once. Break the refactoring into tiny steps. Each step should be a small transformation that preserves behavior.

Bad:

// Old function
function processOrder(order) {
  // 50 lines of mixed logic
}

// New function (completely rewritten)
function processOrder(order) {
  // 60 lines of new logic
}

Good:

// Step 1: Extract validation
function validateOrder(order) {
  // validation logic
}

function processOrder(order) {
  validateOrder(order);
  // rest of logic
}

Step 4: Use the Compiler and Linter

If you're using a statically typed language, let the compiler guide you. Rename a variable and see where it breaks. Linters can also catch common mistakes.

Step 5: Run Tests After Every Change

After each small change, run the tests. If they fail, revert the change and try a different approach. This keeps you from going down a rabbit hole.

Step 6: Use Version Control Effectively

Commit frequently. Each commit should represent a single logical change. This makes it easy to revert if something goes wrong.

git commit -m "Extract validateOrder function"
git commit -m "Simplify discount calculation"

Step 7: Leverage Automated Refactoring Tools

Many IDEs have built-in refactoring tools like "Extract Method", "Rename", and "Inline Variable". These tools are less error-prone than manual changes.

Step 8: Review Your Changes

Before merging, do a diff review. Look for unintended changes in behavior. If possible, have a colleague review the code.

Conclusion

Refactoring doesn't have to be scary. By following these steps, you can improve your codebase with confidence. Start small, keep tests green, and commit often. Your future self will thank you.

Code Review Habits That Actually Stick

Code Atlas — Thu, 23 Jul 2026 08:00:21 +0000

Why Code Reviews Matter

Code reviews are one of the most effective ways to catch bugs, share knowledge, and improve code quality. But without good habits, they become a dreaded chore. Over the years, I've refined a few practices that make reviews productive rather than painful.

Review in Small Batches

A 500-line diff is overwhelming. I ask my team to keep pull requests under 200 lines. Smaller changes are easier to understand, and reviewers can spot issues faster. If a PR is too large, I suggest splitting it into logical commits or separate PRs.

Start with the Big Picture

Before diving into syntax, I read the PR description and check the overall approach. Does it solve the problem? Is the architecture sound? I leave high-level comments first, then move to line-level details. This avoids wasting time on style nits for code that might be restructured.

Use a Checklist

I have a mental (or written) checklist:

Does the code compile and pass tests?
Are there edge cases handled?
Is error handling appropriate?
Are there security concerns (e.g., SQL injection, XSS)?
Is the code readable and maintainable?

This keeps me consistent and prevents me from forgetting important aspects.

Ask Questions, Don't Assume

Instead of saying "This is wrong," I ask "Why did you choose this approach?" or "What happens if this input is null?" This opens a dialogue rather than putting the author on the defensive. Often, there's a reason I hadn't considered.

Leave Positive Feedback

It's easy to only point out problems. I make an effort to comment on what's done well: "Nice use of the strategy pattern here" or "Great test coverage on the edge cases." This encourages good practices and builds trust.

Don't Block on Style

Unless the team has a linting rule, I avoid nitpicking formatting, variable naming, or minor style preferences. Those should be automated. I focus on correctness, performance, and maintainability.

Respond Quickly

I aim to review within 24 hours. Long delays kill momentum. If I can't do a full review, I leave a quick note: "I'll review this tomorrow." The author knows it's not ignored.

Follow Up on Your Own PRs

When I'm the author, I respond to every comment, even if just "Thanks, fixed." I also update the PR description if the code changes significantly. This shows respect for reviewers' time.

Automate the Mundane

Linters, formatters, and static analysis tools catch many issues automatically. I set them up in CI so reviewers can focus on logic and design. This reduces noise and speeds up reviews.

Conclusion

Code reviews are a team sport. By keeping changes small, focusing on substance, communicating respectfully, and automating the trivial, you can turn reviews from a bottleneck into a valuable part of your workflow. Start with one or two habits and build from there.

DEV Community: Code Atlas

Logging Done Right: A Practical Guide

Logging Done Right: A Practical Guide

Why Logging Matters

Choose a Structured Format

Log Levels: Use Them Wisely

What to Log (and What Not to Log)

Error Logging: Include the Stack Trace and Context

Don't Log in Loops

Correlation IDs: Trace a Request Across Services

Log Rotation and Retention

Test Your Logging

Final Thoughts

Naming Things Without Pain

The Real Problem With Naming

Start With the Why

Use Intent-Revealing Names

Keep It Short, But Not Too Short

Consistency Is King

Avoid Abbreviations and Acronyms

When You Can't Think of a Name

The Hardest Names: Booleans and Functions

Refactor Names as You Go

Final Thoughts

A Simple Git Workflow That Scales for Small Teams

The Problem with Git Chaos

The Core Rules

Setting Up the Basics

The Daily Loop

1. Start from a fresh main

2. Make small, focused commits

3. Push and open a PR early

4. Keep your branch up to date

5. Merge with a squash

Handling Common Situations

Hotfixes

Large features

Multiple people on the same feature

Why This Works

Final Tips

Naming Things Without Pain

The Real Problem With Naming

Start With the Why, Not the What

Use the Right Level of Abstraction

Consistency Beats Creativity

The Two-Second Rule

Refactor Names Without Guilt

Practical Heuristics I Use

When You're Stuck: Fake It

A Simple Process for Naming

Final Thoughts

Error Handling Patterns That Actually Scale

Start with the fundamentals

The classic: try/catch

Result objects: no surprises

The Either monad: functional flavor

Async errors: the promise way

Global error handling

Practical advice

Conclusion

Refactoring Safely: A Step-by-Step Guide

Refactoring Safely: A Step-by-Step Guide

1. Understand the Current Behavior

2. Make Small, Atomic Changes

3. Run Tests Frequently

4. Use Version Control as a Safety Net

5. Keep Behavior Identical

6. Leverage the Compiler and Linter

7. Refactor in Layers

8. Use Automated Refactoring Tools When Possible

9. Don't Be Afraid to Rewrite

10. Review and Clean Up

Conclusion

Testing Basics That Actually Pay Off

Start With the Tests That Hurt

Test the Critical Path First

Use the Right Kind of Test for the Job

Make Tests Readable and Maintainable

Run Tests Automatically, Not Manually

Test the Fix, Not the Symptom

1. Start from a fresh `main`