Mastering Clean Code: Naming, Functions, and Testing Best Practices

The Art of Naming

Good naming is difficult, especially for non‑native English speakers, but it pays off by making code more intuitive and expressive. A proper name should be self‑descriptive, indicating what the entity is, why it exists, and how to use it, eliminating the need for explanatory comments.

Examples illustrate the impact of naming:

# bad code

def getItem(theList):
    ret = []
    for x in theList:
        if x[0] == 4:
            ret.append(x)
    return ret

# good code

def getFlaggedCell(gameBoard):
    '''Minesweeper: flagged cells''' 
    flaggedCells = []
    for cell in gameBoard:
        if cell.IsFlagged():
            flaggedCells.append(cell)
    return flaggedCells

Other naming rules include avoiding misleading abbreviations, using searchable identifiers whose length matches their scope, and steering clear of generic placeholders like l or user for a list.

Comments

Well‑written code should need little to no comments; comments exist to compensate for insufficient expressiveness. Overly detailed or outdated comments are harmful. Good comments are limited to legal notices, intent explanations, warnings, TODOs, and highlighting non‑obvious decisions.

# bad
// check to see if the employee is eligible for full benefit
if ((employee.flags & HOURLY_FLAG) && (employee.age > 65)) {
    // ...
}

# good
if (employee.isEligibleForFullBenefits()) {
    // ...
}

Functions

Each function should obey the Single‑Responsibility Principle: it does one thing, and its name should make that clear. Functions should either perform an action ( do_sth) or answer a query ( query_sth), but not both.

public class UserValidator {
    private Cryptographer cryptographer;
    public boolean checkPassword(String userName, String password) {
        User user = UserGateway.findByName(userName);
        if (user != User.NULL) {
            String codedPhrase = user.getPhraseEncodedByPassword();
            String phrase = cryptographer.decrypt(codedPhrase, password);
            if ("Valid Password".equals(phrase)) {
                Session.initialize();
                return true;
            }
        }
        return false;
    }
}

Functions must operate at a single abstraction level. Mixing levels leads to confusing code. For example, pushing an elephant into a refrigerator can be expressed at a high level without detailing how the elephant is moved:

def pushElephantIntoRefrige():
    openRefrige()
    pushElephant()
    closeRefrige()

Parameters should be minimal; many parameters increase test cases and complexity. Boolean flag arguments often violate single‑responsibility and should be split into separate functions.

Testing

Testing, especially unit testing and TDD, is essential for maintaining code quality. Without high‑coverage automated tests, developers hesitate to modify code, leading to decay. Effective test code must be readable, fast, independent, repeatable, self‑validating, and written before the corresponding production code.

You may not write production code until a failing unit test exists.

Write only enough test code to cause a failure; compilation failures count as failures.

Write only enough production code to make the failing test pass.

Fast – tests should run quickly and be automatable.

Independent – tests must not depend on each other.

Repeatable – tests should pass in any environment.

Self‑Validating – tests produce a boolean result, avoiding manual log inspection.

Timely – write tests before the production code they verify.