I've heard people describe poorly written code as making their eyes bleed, but what does that actually mean? What specific habits or design choices make code difficult to read, maintain, or modify even when it produces the correct output? I'd also appreciate practical advice for beginners who want to avoid writing code that frustrates the next person who has to work with it.
5 Answers
Don’t optimize for the fewest lines. Code-golf-style tricks, dense expressions, and chaining everything into one statement may look impressive, but they force readers to mentally unpack the code. Use intermediate variables when they clarify the steps, and write comments about why something unusual is necessary rather than narrating obvious syntax. A useful test is: would I understand this six months from now without reconstructing the whole program?
There isn’t one universal definition of ugly code, and style preferences like braces versus significant whitespace are often subjective. The more objective warning signs are code that is hard to explain, hard to test, difficult to change, or full of unexplained exceptions. As a beginner, use your language’s formatter and idioms, read well-maintained examples, keep functions focused, and ask for feedback on readability rather than only checking whether the result is correct.
Deep nesting and giant functions are classic examples. If a function handles validation, database access, pricing, formatting, and error handling all at once, it becomes difficult to test or change safely. Guard clauses can reduce nesting for simple failure cases, but when the branching represents genuinely different behavior, move parts into small, well-named functions instead of just inverting the conditions.
The biggest offenders are usually clarity problems: clever one-liners that obscure the logic, vague or overly short names, inconsistent formatting, poor organization, and code that ignores the normal conventions of its language. Code should be written for the person who has to understand it later, not just for the compiler. A formatter, consistent project layout, and descriptive names go a long way.
Working output doesn’t automatically mean good code. Repeated copy-and-paste logic, magic numbers, commented-out blocks, unclear state changes, unnecessary global data, and returning unrelated types such as either a value or an error string all make maintenance harder. A future change can easily break one of the hidden assumptions. Prefer small pieces with one responsibility, explicit inputs and outputs, and tests that cover the important behavior.
Guard clauses help with early exits, but they don’t solve every kind of nesting. If the logic is truly branching in several directions, extracting the inner behavior into a named function usually makes the structure much clearer.