How to Write Clean Code: Naming, Comments, Functions, and Testing Best Practices

Introduction

Writing clean code is a universal goal for programmers. "Clean Code" teaches us to distinguish dirty code from clean code and improve through deliberate practice.

1. The Art of Naming

Good names should be descriptive, truthful, and searchable, helping both machines and humans understand code intent.

1.1 Truthful Names

A good variable name tells what it is, why it exists, and how to use it.

1.2 Avoid Misleading Names

Do not use ambiguous or overloaded abbreviations.

1.3 Meaningful Distinctions

Names should convey distinct concepts.

# 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

1.4 Use Readable Words

Names that cannot be read aloud hinder discussion.

1.5 Search‑Friendly Naming

Length should match scope.

1.6 Avoid Cognitive Mapping

Generic names like temp force readers to translate meaning each time.

2. Comments

Expressive code often needs no comments; comments should only fill gaps where code cannot convey intent.

Good comments include legal information, intent explanations, warnings, TODOs, and highlighting non‑obvious decisions.

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

# good
if (employee.isEligibleForFullBenefits())

3. Functions

3.1 Single Responsibility

A function should do one thing, evident from its name.

3.2 Consistent Abstraction Level

All statements in a function should operate at the same level of abstraction.

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

3.3 Parameter Management

Too many parameters increase test cases and complexity; avoid flag arguments.

3.4 DRY (Don’t Repeat Yourself)

Reuse functions where possible, but avoid over‑generalizing that leads to confusing interfaces.

4. Testing

Testing, especially unit testing, is essential for maintaining readable, maintainable, and extensible code.

Key testing principles (FIRST): Fast, Independent, Repeatable, Self‑validating, Timely.

Do not write production code without a failing test.

Write only enough test code to cause a failure.

Write only enough production code to pass the failing test.