Master Clean Code: Naming, Classes, Functions, and Testing Made Simple

1. Why Keep Code Clean?

Unclean code accumulates over time, reducing productivity, making extensions risky, causing crashes, increasing overtime, raising company costs, and in extreme cases leading to project failure.

Code is hard to extend and changes may introduce new bugs.

System crashes become more frequent.

Developers spend extra overtime.

Company incurs additional hiring costs.

Severe neglect can even cause a company to collapse.

2. Naming

Good names increase readability, convey intent, and lower the cost of understanding code. Bad naming, redundancy, and inconsistency should be avoided.

Bad example:

public interface Animal {
    void abc();
}

The method name abc gives no clue about its purpose.

Good example:

public interface Animal {
    void cry();
}

Using a meaningful verb like cry makes the intent clear.

Guidelines:

Use meaningful, descriptive names.

Keep naming consistent across similar responsibilities (e.g., find vs query).

Avoid redundant words such as Variable or Table in names.

Prefer verb‑based prefixes for actions ( getXxx, listXxx).

3. Classes

Well‑designed classes should satisfy Single Responsibility, Open‑Closed, and high cohesion.

3.1 Single Responsibility

A class should have only one reason to change. Benefits include lower complexity, better readability, easier maintenance, and reduced risk of side‑effects.

Example of a class with two responsibilities:

public abstract class Sql {
    // execute SQL
    abstract void insert();
    // count inserts
    abstract void countInsert();
}

Refactor by extracting the counting logic into a separate class:

public abstract class CountSql {
    abstract void countInsert();
}

3.2 Open‑Closed Principle

Software should be open for extension but closed for modification. Adding new behavior should not require changing existing code.

Violating example:

public abstract class Sql {
    abstract void insert();
    abstract void update();
    abstract void delete();
}

To add a query operation, the class must be modified. Refactor by creating subclasses for each operation:

public abstract class Sql {
    abstract void generate();
}
public class CreateSql extends Sql {
    @Override
    void generate() { /* create logic */ }
}
public class UpdateSql extends Sql {
    @Override
    void generate() { /* update logic */ }
}

3.3 Cohesion

High cohesion means that a class’s methods and fields work together to fulfill a single purpose. When cohesion is low, split the class into smaller, focused classes.

4. Functions

Functions should do one thing, have clear names, minimal parameters, no side effects, and appropriate return values.

4.1 Do One Thing

Long functions that handle validation, compression, and result reporting should be broken into smaller helpers.

public String upload() {
    // validation (80 lines)
    // compression (50 lines)
    // return status (5 lines)
    return "0";
}

Refactored version:

public String upload() {
    check();
    compress();
    return "0";
}

4.2 Function Naming

Names must describe intent. Prefer explicit verbs such as appendCharacter or insertCharacter over vague names like addCharacter.

4.3 Parameters

Keep the number of parameters low; encapsulate related data into objects.

Avoid Boolean flags that create two logical paths inside a method.

Do not use output parameters; return results instead.

Bad example with a Boolean flag: void render(Boolean isSuite); Refactored into two separate methods:

void renderForSuite();
void renderForSingleTest();

4.4 Return Values

Separate commands from queries. A method that both performs an action and returns a success flag should be split.

// Bad
public Boolean addElement(Element e);

Refactor:

public void addElement(Element e);
public Boolean isAdd(Element e);

Prefer throwing exceptions over returning error codes to avoid deep nesting.

4.5 Exception‑Based Refactoring Example

public void sendShutDown() {
    try {
        tryToShutDown();
    } catch (DeviceShutDownError e) {
        logger.log(e);
    }
}
private void tryToShutDown() throws DeviceShutDownError {
    DeviceHandle handle = getHandle(DEV1);
    retrieveDeviceRecord(handle);
    pauseDevice(handle);
    clearDeviceWorkQueue(handle);
    closeDevice(handle);
}
private DeviceHandle getHandle(DeviceID id) {
    // ...
    throw new DeviceShutDownError("Invalid handle for:" + id);
}

5. Testing

Testing verifies that clean code works as intended and should itself be clean.

5.1 Test‑Driven Development (TDD)

Write a failing test before production code, then implement just enough code to pass the test. Repeat iteratively.

5.2 FIRST Principles

Fast : tests run quickly.

Independent : tests do not depend on each other.

Repeatable : tests run in any environment.

Self‑validating : tests assert results automatically.

Timely : tests are written before code.

5.3 Given‑When‑Then Pattern

Structure tests into three clear phases: set up data (Given), execute code (When), verify outcome (Then).

@Test
public void shouldReturnItemNameInUpperCase() {
    // Given
    Item mockedItem = new Item("it1", "Item 1", "This is item 1", 2000, true);
    when(itemRepository.findById("it1")).thenReturn(mockedItem);
    // When
    String result = itemService.getItemNameUpperCase("it1");
    // Then
    verify(itemRepository, times(1)).findById("it1");
    assertThat(result, is("ITEM 1"));
}

6. Conclusion

Writing clean code improves readability, extensibility, development efficiency, and reduces overtime, ultimately raising a developer’s skill level. Studying resources such as the book *Clean Code* helps reinforce these principles.