Why Clean Code Matters: Practical Tips to Write Maintainable Java

This article is a learning summary of the book "Clean Code" and explains why clean, readable code is essential for projects, companies, and individual developers.

1. Why Keep Code Clean?

Untidy code accumulates over time, reducing productivity and leading to problems such as difficult expansion, program crashes, overtime, increased hiring costs, and even company failure.

1.1 Start Clean from the Beginning

Write clean code from the start and refactor any messy code immediately; never postpone improvements. The principle is captured by the phrase: later equal never Delaying refactoring only increases technical debt.

1.2 How to Write Clean Code?

Clean code should be highly readable, avoid duplication, follow design pattern principles, and adhere to SOLID principles (Single Responsibility, Open/Closed, Liskov Substitution, Interface Segregation, Dependency Inversion, etc.).

2. Naming

Good naming improves readability and reduces understanding cost.

2.1 Bad Naming Examples

public interface Animal { void abc(); }

The method name abc conveys no meaning. A better name is: public interface Animal { void cry(); } Other naming issues include inconsistent naming, redundant words, and unclear prefixes. Consistent, meaningful names should be used throughout.

3. Classes

Clean classes should satisfy:

Single Responsibility

Open/Closed Principle

High Cohesion

3.1 Single Responsibility

A class should have only one reason to change. Overly large classes usually have multiple responsibilities and should be split.

public abstract class Sql { void insert(); void countInsert(); }

Refactor by extracting responsibilities into separate classes:

public abstract class CountSql { void countInsert(); }

3.2 Open/Closed Principle

Software should be open for extension but closed for modification. Adding new functionality should not require changing existing code. public abstract class Sql { void generate(); } New operations are added by subclassing:

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

3.3 Cohesion

High cohesion means that class members are closely related and serve a single purpose. Low cohesion indicates the class should be split.

4. Functions

Clean functions should:

Do one thing

Have descriptive names

Have clean parameters

Return appropriate results

4.1 Do One Thing

Functions should be short and focused. Example of a poorly designed function:

public String upload() { /* validate (80 lines) */ /* compress (50 lines) */ return "0"; }

Refactor into smaller steps:

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

4.2 Function Naming

Names should be self‑explanatory. Bad example:

public String addCharacter(String originString, char ch);

Better alternatives:

public String appendCharacter(String originString, char ch);

public String insertCharacter(String originString, char ch, int position);

4.3 Parameters

Prefer few parameters; encapsulate related data into objects when more than three are needed.

public List<Student> findStudent(int age, String name, String country, int gender);

Refactor to:

public List<Student> findStudent(Student criteria);

4.4 Return Values

Separate commands from queries. Use exceptions instead of error codes.

public void addElement(Element e) throws DeviceShutDownError { /* ... */ }

5. Testing

Testing validates code correctness and should also be clean.

5.1 Test‑Driven Development (TDD)

Write tests before code, ensure tests initially fail, then develop code to pass them.

5.2 FIRST Principles

Tests should be Fast, Independent, Repeatable, Self‑validating, and Timely.

5.3 Given‑When‑Then Pattern

@Test public void shouldReturnItemNameInUpperCase() { // Given Item mocked = new Item("it1", "Item 1", ...); when(itemRepository.findById("it1")).thenReturn(mocked); // 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. Every developer should read "Clean Code" to enhance coding ability and mindset, and adopt clean coding practices early rather than relying on later refactoring.