Principles of Clean Code: Naming, Functions, and Testing

Writing clean code is a universal goal for programmers; the book "Clean Code" defines dirty code as a "swamp" and clean code as expressive, elegant, and maintainable.

1. Naming Good names should be descriptive, truthful, and searchable. Examples show a bad function versus a good one:

# 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 game, flagged: flipped'''
   flaggedCells = []
   for cell in gameBoard:
      if cell.IsFlagged():
         flaggedCells.append(cell)
   return flaggedCells

Additional naming advice includes avoiding misleading names, using readable words, and choosing names whose length matches their scope.

# bad

def copy(a_list, b_list):
    pass

# good

def copy(source, destination):
    pass

2. Comments Proper comments compensate for code that fails to express intent; ideally code should be self‑explanatory. Acceptable comments include legal information, intent explanations, warnings, TODOs, and highlighting important non‑obvious logic. Overly stale or incorrect comments are harmful.

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

# good
if (employee.isEligibleForFullBenefits())

3. Functions Functions should have a single responsibility and a consistent abstraction level. A function should either perform an action (do_sth) or query data (query_sth), not both. Example of a function that mixes responsibilities:

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 should avoid many parameters, especially flag arguments, and should not return output parameters that are hard to understand. Reuse is encouraged, but only when functions respect the single‑responsibility principle.

4. Tests High‑quality code depends on readable, maintainable, and automated tests. The article lists test principles (FAST: Fast, Independent, Repeatable, Self‑validating, Timely) and TDD rules that forbid writing production code before a failing test.

Overall, the article records personal reflections on "Clean Code" and emphasizes expressive naming, minimal and meaningful comments, well‑designed functions, and rigorous testing as essential practices for high‑quality software.