Best Practices for Writing Clean Java Code

src
    ├── main
    │   ├── java                   Application/Library sources
    │   ├── resources              Application/Library resources
    │   ├── filters                Resource filter files
    │   └── webapp                 Web application sources
    │   
    └── test
        ├── java                   Test sources
        ├── resources              Test resources
        └── filters                Test resource filter files

package com.example.project;

public class Person {
    private String firstName;
    private String lastName;

    public Person(String firstName, String lastName) {
        this.firstName = firstName;
        this.lastName = lastName;
    }

    public String getFullName() {
        return firstName + " " + lastName;
    }

    public static final int MAX_AGE = 100;

    public boolean hasValidName() {
        return firstName != null && lastName != null;
    }
}

Poor code readability makes debugging difficult and increases the effort required to maintain the codebase. This can be challenging, especially when trying to onboard new developers into your project. Therefore, as you develop software, ensure that you don’t prioritize reusability over readability.

4. Lint your code with Static and Dynamic analysis tools

Static and dynamic code analysis tools complement each other. Both dynamic and static analysis tools can help in writing clean Java code. Static analysis tools allow you to inspect your application source code and ensure adherence to coding standards, spot vulnerabilities, and detect bugs during development.

On the other hand, dynamic analysis allows you to test your application at runtime. It allows you to measure your application’s performance, behavior, and functionality and identify runtime errors, memory leaks, and resource consumption reducing the chances of running into issues in production.
Digma is a runtime linter that lets developers quickly identify risky code, potential errors, and bottlenecks in complex codebases. Digma leverages OpenTelemetry behind the scene to collect data such as traces, logs, and metrics. Once the data is collected, Digma analyzes it to detect meaningful insights about the code. It looks for regressions, anomalies, code smells, or other patterns that can be useful for knowing about the code, allowing you to push clean Java code to production.

5. Use Meaningful comments and documentation

Obsessive commenting is something I struggled with, especially early on in my software development career. This is something that most developers struggle with. Improper use of comments indicates that your code is a symptom of bad programming. 

Proper use of comments and documentation can serve an important role in writing clean Java code. While code should be readable and self-explanatory, sometimes it’s impossible to avoid complex logic. However, using strategic comments within the code, you can explain the logic behind some parts of the code that are not straightforward.

In Java, developers can leverage two types of comments documentation comments and implementation comments. Documentation comments target codebase users, while implementation comments are meant for developers working on the codebase.

/**
 * This class represents a RESTful controller for managing user resources.
 * It provides endpoints for creating, retrieving, updating, and deleting users.
 */
@RestController
@RequestMapping("/api/users")
public class UserController {

    /**
     * Retrieves a user by ID.
     *
     * @param id The ID of the user to retrieve.
     * @return The user with the specified ID.
     */
    @GetMapping("/{id}")
    public ResponseEntity<User> getUserById(@PathVariable("id") Long id) {
        // Implementation omitted for brevity
    }

    /**
     * Creates a new user.
     *
     * @param user The user object to create.
     * @return The created user.
     */
    @PostMapping
    public ResponseEntity<User> createUser(@RequestBody User user) {
        // Implementation goes here
    }

//Rest of the code

6. Use consistent and proper code formatting: whitespaces and indentation

Code formatting may not seem like a big issue when you’re working on a personal project whose code may never be maintained by another developer. However, consistent code formatting and style are critical when working with a team of other developers. 

Maintaining a consistent formatting and coding style in your team and codebase ‌is important if you wish to write clean Java code as a team. Whitespace and indentation are essential in maintaining a consistent coding style. 

Good usage of whitespace between operators, commas, and around flow statements enhances code readability. For instance, you can organize code into logical groups using whitespaces, enhancing readability and visual clarity. 

Indentation refers to using tabs or spaces within loops, methods, and control structures. Although there is no enforced convention for code indention in Java, you can choose to adopt popular convection and use it consistently.

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class MyApplication {

    public static void main(String[] args) {
        SpringApplication.run(MyApplication.class, args);
    }
    
    // Rest of the code goes here
    // ...

}

7. Restrict the number of method parameters

Parameters are necessary when working with methods. However, care should be taken to avoid using too many parameters in one method. Too many parameters may indicate that your method is addressing more than one concern and violates the single responsibility principle. 

Too many method parameters make your code less readable since keeping track of their types and meanings is difficult. To write clean Java code, you should: limit the number of method parameters and use objects or data structures instead of individual parameters or group-related parameters into objects. 

Here is an example of a Java method with too many method parameters.

public void processOrder(String customerName, String shippingAddress, String billingAddress,
                         String productName, int quantity, double price, boolean isExpressShipping) {
    // Method implementation
}

Here is how we can refactor the code above by grouping related parameters into an object to improve readability.

public class Order {
    private String customerName;
    private String shippingAddress;
    private String billingAddress;
    private String productName;
    private int quantity;
    private double price;
    private boolean isExpressShipping;

    // Constructors, getters, and setters

    // Other methods related to an order
}

public void processOrder(Order order) {
    // Method implementation
}

8. Leverage Unit Tests and Test Driven Development (TDD)

Unit testing and TDD are very common practices in software development. Unit testing involves writing tests for individual functions, methods, and classes to ensure that they work in isolation. TDD is also a popular development practice that involves writing tests before code. 

Both Unit tests and a TDD approach can propel your efforts toward writing clean Java code. Unit tests allow you to verify correctness, detect bugs early, and write more modular code. TDD provides immediate feedback and increases your confidence in writing reliable and maintainable code.

Source: Twitter

9. SOLID principles

The SOLID principles by Robert C. Martin (Uncle Bob) are very popular; every developer should know them.  These principles can also help you write clean, maintainable, and scalable code. 

Let’s discuss how each of the principles in the SOLID acronym can help you write clean Java code. 

Single Responsibility Principle (SRS): The single responsibility principle states that a class should only have one responsibility. Following the SRS principle guarantees that we write concise, readable, and maintainable code.

Open-closed principle (OCP): The OCP states that classes should be open for extension but closed for modification except when fixing bugs. This principle allows you to add new features without introducing bugs or breaking existing functionality. In Java, you can use interfaces or abstract classes to extend the functionality of existing classes. 

Liskov substitution principle (LSP): The LSP principle states that we should be able to use superclasses with their respective subclasses interchangeably without breaking the functionality of our program. Using this principle allows you to use inheritance correctly and write decoupled clean Java code.

Interface Segregation Principle: States that we should opt for smaller focused interfaces instead of large monolithic ones. Using this principle allows us to write modular and clean Java code where the implementing classes focus only on methods that concern them.

Dependency Inversion Principle (DIP): This principle emphasizes loose coupling, guaranteeing that components such as classes only depend on abstractions and not on their concrete implementations. DIP helps us enforce clean Java code using Inversion of Control (IoC) and dependency injection.

10. Keep It Simple, Studio (KISS), and Don’t Repeat Yourself (DRY) principle

KISS and DRY are very fundamental concepts in software development and can help you write clean Java code. The DRY principle states that as a developer, you should ensure that your code is not duplicated multiple times across the system. Eliminating code duplication improves your code maintainability and makes finding and fixing bugs easier. 

The KISS principle emphasizes that we should strive to keep the design and development of the software we build simple and straightforward. By following this principle, you can avoid unnecessary complexity in your code and instead opt to write simple and understandable code. 

The KISS principle promotes the maintainability of your code and makes it more readable. Maintainable and readable code improves collaboration and eases the onboarding of developers into the project. 

11. The Source Files Structure

A typical source file in Java contains different elements that are key in running any Java program. To maintain the readability of your code, you should enforce a consistent source file structure. Although there is no one-size-fits approach to structuring your source file, there are popular style guides that you can follow. 

Normally a typical ordering of a source file structure in Java begins with package statements followed by static and non-static import statements, preceded by one primary top-level class. 

    // Class variables
    private static int count;
    private String name;
    
    // Instance variables
    private int age;
    private List<String> hobbies;

    // Constructors
    public MyClass() {
        // Constructor implementation
    }
    
    public MyClass(String name, int age) {
        // Constructor implementation
    }
    
    // Methods
    public void setName(String name) {
        // Method implementation
    }
    
    public String getName() {
        // Method implementation
    }
    
    public void addHobby(String hobby) {
        // Method implementation
    }
    
    // Other methods
    
}

// Additional classes (if any)
class MyStaticClass {
    // Class implementation
}

12. Avoid Hard coding values

Hardcoding refers to embedding values directly into your program’s source code instead of using variables. Altering the source code of your program is the only way to change values hardcoded into your programs. Hardcoded values limit reusability and testability and can also lead to duplication and undesired behavior from your program. 

To improve code reusability, testability, and maintainability, which are key features of clean Java code, it is important that you avoid hard coding values in your program source code. Instead, replace hard-coded values with abstractions such as constant variables or enums.

Here’s an example of a Java program with hardcoded values.

@RestController
public class HelloWorldController {

    @GetMapping("/hello")
    public String sayHello() {
        return "Hello, World!";
    }
    
    @GetMapping("/user")
    public String getUser() {
        // hardcode values
        String username = "John";
        int age = 30;
        return "Username: " + username + ", Age: " + age;
    }
    
    // Other controller methods
    
}

Conclusion

Writing clean Java code is key to developing high-quality software.

In this article, we have shared some of the best and most common practices that can help you write clean Java code. However, it is important to note that this isn’t a definitive list of what it takes to write clean Java code. Other key factors that contribute to writing clean Java code include the culture, tools available, and goals of the team you’re working with. You can write readable, testable, extensible, and modular code by embracing these principles.

FAQ

What is clean code?

Clean code refers to readable, and maintainable code that is written based on best practices and conventions. It is code that is easy to understand, modify, and extend by both the original author and other developers. who inherited the code.

Why is it important to write clean Java code?

Clean code improves readability, enhances collaboration, reduces the chances of introducing bugs, and makes maintainability easier.

Are there tools that can help in writing clean Java code?

There are many tools that aid the process of writing clean Java code. Some include static code analysis tools such as SonarQube, FindBugs, and Digma. IDEs such as IntelliJ and Eclipse can also be helpful.

Which resources can I use to learn more about writing clean Java code?

Plenty of blogs and online tutorials exist, such as Baeldung. I would also recommend books such as “Clean Code: A Handbook of Agile Software Craftsmanship” by Robert C. Martin and “Effective Java” by Joshua Bloch.