I've heard people describe difficult code by saying that reading it made their eyes bleed. I understand that code can be buggy, but what makes code feel bad or painful to work with even when it produces the correct output? What are the biggest readability and maintainability problems, and what habits should a beginner develop to avoid writing code like that?
4 Answers
Deeply nested conditionals are a classic example. Guard clauses can handle early failure cases near the top of a function, and genuinely separate branches can often be moved into well-named helper functions. If a function keeps growing, that is usually a sign that its responsibilities need to be split up.
The biggest offenders are usually poor readability choices: clever one-liners instead of clear code, inconsistent formatting, vague names, excessive nesting, and functions that handle several unrelated responsibilities. Code should be written for the next person who has to understand or modify it, not just for the compiler.
Shorter is not automatically better. Code-golf-style solutions may be impressive, but a straightforward solution spread over a few readable lines is usually much easier to maintain.
Working code can still be bad code if nobody can safely change it. A giant function that calculates prices, validates input, updates state, and formats output is much harder to test than several focused functions. Prefer clarity over cleverness, use intermediate variables when they make the steps obvious, and add comments to explain why something unusual is necessary rather than merely repeating what the code does.
A useful test is to imagine returning to the code six months later. If you would need a debugger just to discover what each section means, it probably needs clearer structure or names.
Naming and organization matter more than many beginners expect. Names like `tmp`, `ptr`, `data`, or `x` may be acceptable in a tiny local context, but they become painful when used across a larger scope. Avoid giant files, massive functions, copy-pasted logic, magic numbers, commented-out code, and mixed responsibilities. Use a formatter and follow the normal conventions of the language and project.
Guard clauses help with error checks, but they do not magically fix real branching complexity. Extracting the inner logic into a function with a descriptive name is often the better solution.