Master Clean Code: Naming, Classes, Functions, and Testing Best Practices

Why Clean Code Matters

Unmaintained code becomes hard to extend, prone to crashes, forces overtime, and increases operational cost. Writing clean code from the start prevents these problems.

1. Naming

Clear, meaningful names reduce the cognitive load for readers and callers.

1.1 Bad naming example

public interface Animal { void abc(); }

The method name abc conveys no intent.

1.2 Good naming example

public interface Animal { void cry(); }

cry

clearly describes the method’s purpose.

1.3 Consistency

Inconsistent naming (e.g., findOneById vs. queryAllStudent) should be unified.

public interface StudentRepository extends JpaRepository<Student, String> {
    Student findOneById(@Param("id") String id);
    List<Student> findAll();
}

1.4 Redundancy

Avoid unnecessary words in identifiers.

// Prefer concise prefixes
getXxx();
listXxx();

2. Class Design

Single Responsibility Principle (SRP)

Open/Closed Principle (OCP)

High Cohesion

2.1 Single Responsibility

A class should have only one reason to change. Large classes usually violate SRP.

2.2 Open/Closed Principle

Software should be open for extension but closed for modification. Extract common behavior into abstract bases and create concrete subclasses for new functionality.

public abstract class Sql {
    public abstract void generate();
}

public class CreateSql extends Sql {
    @Override
    public void generate() { /* implementation */ }
}

public class UpdateSql extends Sql {
    @Override
    public void generate() { /* implementation */ }
}

2.3 Cohesion

High cohesion means most methods operate on the same data, indicating a well‑focused class.

3. Function Design

Do one thing only

Use expressive names

Keep parameters minimal

Return clear results

3.1 Do One Thing

Break large methods into small, single‑purpose steps.

public String upload() {
    // Validate image
    check();
    // Compress image
    compress();
    // Return status
    return "0";
}

3.2 Function Naming

Names should describe intent. Prefer explicit verbs such as appendCharacter over vague addCharacter.

3.3 Parameters

Limit the number of parameters; group related data into value objects.

Avoid Boolean flags—split into separate methods.

Do not use output parameters; return results directly.

// Bad: Boolean flag
render(Boolean isSuite);
// Good
renderForSuite();
renderForSingleTest();

3.4 Return Values

Separate commands from queries. Use exceptions instead of error codes to simplify control flow.

public void sendShutdown() {
    try {
        tryToShutdown();
    } catch (DeviceShutdownError e) {
        logger.log(e);
    }
}

private void tryToShutdown() throws DeviceShutdownError {
    DeviceHandle handle = getHandle(DEV1);
    // ... perform shutdown steps ...
}

private DeviceHandle getHandle(DeviceID id) throws DeviceShutdownError {
    // ... logic ...
    throw new DeviceShutdownError("Invalid handle for:" + id);
}

4. Testing

4.1 Test‑Driven Development (TDD)

Write a failing test first, then implement just enough code to make it pass, and finally refactor.

4.2 FIRST Principles

Fast – tests run quickly.

Independent – tests do not depend on each other.

Repeatable – tests produce the same result everywhere.

Self‑validating – assertions verify outcomes automatically.

Timely – tests are written before production code.

4.3 Given‑When‑Then Pattern

Structure tests into three clear phases.

@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"));
}

5. Code‑Quality Tools

Static analysis tools such as SonarLint detect duplicated code, potential null‑pointer dereferences, deep nesting, and encourage modern APIs (e.g., LocalDate, LocalDateTime). They also provide measurable metrics like bug density and duplication rate.

References

Robert C. Martin, Clean Code

https://www.cnblogs.com/sunny3158/p/16353643.html

https://blog.csdn.net/qq_42289636/article/details/108762981