Words for things that feel wrong

1. The premise

When something is wrong with code, the first signal is a feeling: something is off here. Beginners feel it dimly and can't act on it. Seniors feel it sharply and can name it in one phrase. The naming is the difference between a feeling and a fix.

The named version of "something is off" is what we call a code smell — a generic name for a specific kind of wrong. Smells aren't bugs. Smells are signs that the code is about to become a bug, or already is one that hasn't fired yet.

Knowing the words is the cheapest way to upgrade your taste, because you can use them tomorrow without learning anything else.

2. The basic vocabulary

A starter set, in plain language:

• Long function. When a function is so long you have to scroll to see it whole, it's a smell. Almost always splittable. If you can't split it, the seam between the parts wasn't found yet.
• Doing two things. A function that does X and also Y is harder to test, harder to name, and harder to change than two functions. The hint is the word "and" in your description of what it does.
• Magic number. A literal value (like 7 or 0.85) that's not obviously meaningful. Almost always wants to be a named constant.
• Comment that explains what. A comment that explains what a line does is a smell — the line itself should have said it via good naming. A comment that explains why is usually fine and sometimes essential.
• Dead code. Code that runs but whose result isn't used, or code branches that can't be reached. Lying to readers about what matters.
• Long parameter list. Four parameters is fine. Eight is a smell — the function is probably doing too much, or several of those parameters belong together as one object.
• Copy-paste twin. Two pieces of code that look almost identical. They will drift, silently, over time, into two slightly different bugs.
• Shotgun change. A single conceptual change that requires editing seven files. The boundary is in the wrong place.

3. Why naming helps

The moment you can name the smell, two things happen.

One: you can act on it. "This is doing two things" is a problem you can solve. "Something feels off" is not.

Two: you can communicate it. In a code review, "this function is doing two things" lands. "I don't like this" does not.

Both effects compound. After you've named a smell five times, you start seeing it from across the room, before you've even read the code carefully. That's the upgrade.

4. Try it