DEV Community

Cover image for Your Comments Are Rotting, So I Hope Your Tests Have A Long Shelf Life
Doogal Simpson
Doogal Simpson

Posted on • Originally published at doogal.dev

Your Comments Are Rotting, So I Hope Your Tests Have A Long Shelf Life

#java #programming #webdev #beginners

Comments are liars.

Wiki pages are fantasies written by people who haven’t looked at the codebase in six months. Slack threads are lost to the void.

When you open a legacy file—one written by a developer who left the company three years ago (or by you during a caffeine bender)—there is only one source of truth left.

The Test Suite.

But here is the hard truth: Most developers write tests that are functionally useless to humans. They write tests to satisfy a CI pipeline or a manager’s "80% Code Coverage" metric. They treat testing like a chore.

A Coder names tests based on the function name.
A Professional names tests based on behavior.

If you want to move from "Junior" to "Senior," you need to stop writing tests for the computer and start writing them for the Software Archaeologist who has to dig through your code next year.

Here is how we turn tests into Living Documentation.

The Trap: Naming for Syntax

We have all seen this test file. We have all written this test file.

You have a function called checkLogin. You need a test. So, you create a test called checkLogin.

This is the "Box-Ticking" mindset. You are doing the homework, but you aren’t learning the lesson.

// Before: The "Mystery Box" Test

When "Future You" reads this test, what do you learn? You learn that the function exists. That’s it. You have to read the implementation details of the test just to understand what the code is supposed to do.

// ❌ The Junior Trap
// The name tells us nothing. We have to parse the code mentally.

test('checkLogin', () => {
  const user = { id: 1, sub: 'active' };
  const res = login(user);
  expect(res).toBe(true);
});

test('checkLogin2', () => {
  const user = { id: 2, sub: 'expired' };
  const res = login(user);
  expect(res).toBe(false);
});
Enter fullscreen mode Exit fullscreen mode

If checkLogin fails in the build pipeline, the error message will say: FAIL: checkLogin.

Great. Why did it fail? Did the database crash? Did the logic change? Was it a bad password? The test name gives you zero clues. You now have to context-switch, open the file, and debug.

The Pro Move: Tests as Specs

A Professional views the test suite as a Specification Document.

We don't care about the function name; we care about the Behavior. When we name a test, we are describing a rule of the system. We are leaving a breadcrumb trail for the next developer.

We use the AAA Pattern (Arrange, Act, Assert) to visually structure the code.

// After: The Living Documentation

Look at how this changes the reading experience.

// ✅ The Professional Move
// The test names document the business rules.

describe('Authentication Service', () => {

  test('allows access when the subscription is active', () => {
    // ARRANGE: Set the stage
    const activeUser = { id: 1, subscriptionStatus: 'active' };

    // ACT: Trigger the behavior
    const result = login(activeUser);

    // ASSERT: Verify the result
    expect(result).toBe(true);
  });

  test('throws 401 error when the subscription is expired', () => {
    // ARRANGE
    const expiredUser = { id: 2, subscriptionStatus: 'expired' };

    // ACT & ASSERT
    expect(() => {
        login(expiredUser)
    }).toThrow('401: Subscription Required');
  });

});
Enter fullscreen mode Exit fullscreen mode

Why this works:

  1. It reads like a sentence: "Allows access when the subscription is active." You don't need to read the code to know the business rule.
  2. Instant Debugging: If the second test fails, the CI log says: FAIL: throws 401 error when the subscription is expired. You know exactly what broke without opening the file.
  3. The AAA Pattern: By separating Arrange, Act, and Assert with newlines, the test becomes scannable.

The "Senior" Mindset

When you write a feature, the logic is fresh in your head. You know why you wrote that if statement.

But in six months, that context is gone.

If you rely on comments to explain the "why," you are gambling that the comments were updated when the code changed (spoiler: they weren't).

Tests never lie. If the test passes, that is how the system works.

Don't write tests to prove your code works. Write tests to explain how your code works. That is the difference between writing code and engineering software.

Stop writing code just to please the compiler.

This article was an excerpt from my handbook, "The Professional Junior: Writing Code that Matters."

It’s not a 400-page textbook. It’s a tactical field guide to unwritten engineering rules.

👉 Get the Full Handbook Here

Top comments (0)