Why Clean Code Matters: Naming, Functions, and Testing Secrets Revealed

Writing clean code is a universal goal for programmers. The book Clean Code defines dirty code (often called a "shit mountain") and explains that the only metric for code quality is WTF/min. It cites insights from Bjarne Stroustrup, Grady Booch, Dave Thomas, and Ron Jeffries.

The Art of Naming

Good names should be descriptive, convey purpose, and be easy to read and search. Misleading or ambiguous names lead to confusion.

Example of improving 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):
   '''扫雷游戏，flagged：翻转'''
   flaggedCells = []
   for cell in gameBoard:
      if cell.IsFlagged():
         flaggedCells.append(cell)
   return flaggedCells

Other naming guidelines include avoiding misleading terms, using real words, and matching name length to scope.

If a name cannot be read aloud, discussions become like "stupid birds".

Comments

Expressive code should need little commenting; comments compensate for failures to express intent.

The proper use of comments is to compensate for our failure to express ourselves in code.

Good comments include legal information, intent explanations, warnings, TODOs, and highlighting seemingly unreasonable code that has a purpose.

Functions

Each function should have a single responsibility and its name should clearly describe its purpose. Functions should operate at a single abstraction level.

Example of abstraction:

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

Reading code breadth‑first (top‑down) helps understand overall structure before diving into details.

Function parameters should be minimal; excessive parameters increase test 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. The article emphasizes the FIRST criteria:

Fast – tests should run quickly and be automated.

Independent – tests must not depend on each other.

Repeatable – tests should pass in any environment.

Self‑Validating – tests produce a boolean result.

Timely – tests are written before the production code they verify.

Adhering to these principles ensures readable, maintainable, and reliable test suites.