Java Clean Coding

Java Clean Coding

Overview

Here, we’ll cover the basics of Java Clean Coding. We’ll also learn how to write clean code in Java and why that’s crucial. We’ll also examine if there are any available tools to assist us.

 

What Is a “Clean Code?”

As a result, before we get into clean code specifics, let’s define clean code first. Honestly, there isn’t a single response to this question that is perfect. In programming, several commonalities lead to universal concepts. Because each programming language and paradigm has its own subtleties, we must adapt our techniques accordingly.

Generally speaking, clean code can be defined as code that any developer can read and modify. Even while this may appear to be an oversimplification of the notion, we’ll see how this builds up later in the instructional Martin Fowler‘s name is likely mentioned whenever we hear about clean code. When he discusses clean code in one of the places, he says:

A computer can interpret any code that a human can write. Humans can understand good code because good programmers write it.

 

Clean Code: Why Should It Matter?

It’s not a talent; writing clean code is a matter of personal habit. A developer’s skill set develops through practice and exposure to new situations. What’s the point of writing clean code if we’re not going to use it? Is it enough to know that our code will be easier for others to understand? We’ll find out!

A clean coding philosophy can help us reach a wide range of desirable outcomes when it comes to developing software. Let’s take a closer and precise glance at each one:

• Having a well-maintained codebase means that any software we create has a useful life and must be updated and maintained over time. It is vital to write code that is straightforward to modify and maintain in the future.
• The software can exhibit unexpected behavior for a variety of reasons, both internal and external. This makes troubleshooting a lot easier. When it comes to fixes and availability, it may necessitate a speedy turnaround. Clean coding principles make it easier to find and fix bugs in software.
• Streamlined Onboarding: Throughout the life of a piece of software, it will be updated and maintained by several different developers. Faster onboarding is necessary to maintain high levels of productivity, and clean code aids in this effort.

 

Clean code has the following characteristics

Several distinctive features distinguish cleanly coded codebases from others. Here are the features: 

• It is vital to write code that is focused on a specific problem. It shouldn’t do anything that isn’t directly linked to the topic at hand. Methods, classes, packages, and modules all fall under this umbrella.
• Keeping things simple is the most important and frequently overlooked quality of clean code by a long shot. Software design and implementation must be as easy to understand and apply to obtain the intended results; Codebases become more error-prone and difficult to comprehend and manage as they become more complicated.
• Clean code, while simple, must be able to tackle the issue at hand. Automated testing is preferable but not required for testing the codebase. As a result, it is easy to make changes to the codebase without risking breaking everything.

 

In order to accomplish the objectives outlined above, we need to use these tools. Rather than having to refactor later, it’s better to start creating with these traits in mind. Software lifecycle costs are reduced as a result of this.

 

Java clean coding 

Java is a great platform for implementing clean code concepts, so let’s explore how we can do it here. Our code can be cleaner thanks to Java’s best practices. We’ll break them down into categories and show you how to write clean code using code samples to help you learn.

 

The structure of the project for Clean Code

Even though Java doesn’t mandate a specific project structure, it’s always beneficial to adhere to a consistent pattern when organizing our source files and other code components. Maven, a popular Java build tool, dictates a specific project structure for its users. There is nothing problematic with sticking to a standard.

Let’s have a look at folders Maven recommends:

• src/main/java: This directory contains the source files for Java.
• src/main/resources: Like the attributes of resource files
• Src/test/java: Java source files to be tested in.
• Src/test/resources: Properties and other resource files can be used for testing purposes.

Similar to this, there are several common Java project structures, such as Bazel, that we may choose from based on our audience and needs.

 

Naming Conventions 

If we adhere to naming conventions, our code will be easier to read and maintain. The creator of Spring, Rod Johnson, stresses the importance of naming standards in Spring.

Assuming you know what something does, you’ll have an easier time figuring out what it’s called in Spring.

When it comes to naming things in Java, Java has a set of conventions that must be followed. A well-named function or method can tell you a great deal about the author’s goal when it comes to coding. Here are some major examples: 

To put it simply, classes are blueprints for objects that typically represent real-world items in a computer program. Consequently, it makes sense to employ nouns to describe classes:

public class Customer {

}

 

When an object is generated from a class, the object’s state can be stored in a variable in Java. The name of a variable should be specific enough to convey its purpose:

public class Customer {

public class Customer {     private String customerName;

}

A method is considered an action that can be taken on the state of an object that was formed from a Java class. Using verbs in the names of methods is, therefore, a good idea:

public class Customer {

   private String customerName;

    public String getCustomerName() {

        return this.customerName;

    }

}

There are additional recommended practices like camel casing that we should keep in mind for the sake of readability, even though we have only addressed the name of an identifier in Java. There may be additional naming rules for interfaces, enums, and constants.

 

Structure of the source files for Clean Code

Elements can be added to a source file. Even though the Java compiler imposes some structure, the majority of its functionality is flexible. The readability of a source file can be greatly improved by following a strict sequence of elements in the file. There are some well-known style guides, such as Google’s and Spring’s.

Let’s have a look at what a normal source file should look like:

• Affirmation of purchase
• Statements can be imported.
• All of the static imports
• Imports of non-static data
• Only one top-level class is available
• A class’s properties
• Variables that are specific to a given instance.
• Constructors
• Methods

On top of that, methods can be categorized according to their purpose or range of use. There is no single best convention, and the notion should be decided once and then continuously implemented.

Look at this well-formed source code:

 # /src/main/java/com/baeldung/application/entity/Customer.java

package com.baeldung.application.entity;

import java.util.Date;

public class Customer {

    private String customerName;

    private Date joiningDate;

    public Customer(String customerName) {

        this.customerName = customerName;

        this.joiningDate = new Date();

    }

    public String getCustomerName() { 

        return this.customerName; 

    }

    public Date getJoiningDate() {

        return this.joiningDate;

    }

}

 

Whitespaces

There is no doubt that short paragraphs are simpler to read and grasp than long blocks of text. Similarly, reading code isn’t much different. Whitespaces and blank lines can improve the readability of code if they are inserted in the right places.

In this scenario, the objective is to provide logical groupings in the code to aid in a reader’s comprehension. No single rule to follow here, but a basic set of recommendations and an inherent aim to put readability at the center:

• Static blocks, fields, constructors, and inner classes must all have two blank lines preceding them.
• After a multiline method signature, a single blank line.
• Separating reserved terms like if, for, and catch from parenthesis with a single space.
• Like otherwise, catch from closing parentheses, a single space separates reserved terms.
• This isn’t considered a full and complete list, but it should give us a general direction to go in.

 

Indentation in Clean Code

Although it may seem that it’s not that important, a well-indented code is considerably easier to read and understand. No single Java code indentation convention exists. You can either follow a well-known convention or develop your own and stick to it across the board.

Let’s take a glance at the most significant requirements for indentation.

Use four spaces as a unit of indentation, which is a common practice. Some rules recommend using tabs instead of spaces. As long as you stick to your routine, you’ll be on your way to success!

Normally, the line length should be limited to 80 characters, although this can be increased due to the larger displays used by developers today.

For the sake of consistency, we must break several expressions into many lines:

• After a comma, the stop method calls.
• Before an operator, break apart expressions.
• Wrapped lines should be indented to improve readability (we here at Baeldung prefer two spaces)

The following is an example:

List<String> customerIds = customer.stream()

  .map(customer -> customer.getCustomerId())

  .collect(Collectors.toCollection(ArrayList::new));

 

The parameters of the method

Methods can’t function properly without parameters. If you have a big parameter list, it can be tough to read and comprehend the code. To put it another way, where should the line be drawn? What are the best practices that could benefit us?

 

Keep the parameters of a method under three, which is one of the best options.

• You may want to consider reworking the method if it requires more than the recommended number of parameters, as a big parameter list indicates that the method may be doing more than one thing
• Custom-types may be an option, but care must be taken to avoid dumping non-related parameters into a single type.
• Although this recommendation can be used to evaluate the readability of the code, we should not get too nitpicky with it.

Let’s have a look at an example:

public boolean setCustomerAddress(String firstName, String lastName, String streetAddress, 

  String city, String zipCode, String state, String country, String phoneNumber) {

}

 

// This can be refactored as below to increase readability

 

public boolean setCustomerAddress(Address address) {

}

 

Hardcoding for Clean Code

When values are hardcoded into software, they might have a variety of unintended consequences. Duplication can make change more difficult, for example. If the values are to be dynamic, this can often lead to unwanted behavior. There are several approaches to restructure hardcoded values, including the following:

• Consider using Java enums or constants instead.
• Alternatively, you can use class-level or different class-file constants in their place.
• If feasible, use values that may be retrieved from the environment or configuration.

The following is an example:

rivate int storeClosureDay = 7;

// This can be refactored to use a constant from Java

private int storeClosureDay = DayOfWeek.SUNDAY.getValue()

Once again, there is no set rule to follow in this situation. However, we must keep in mind that some will have to understand and maintain this code in the future. Consistency is our primary key when it comes to a convention.

 

Code Comments

It is helpful to read code with code comments in order to understand the non-trivial features. In addition, care must be made not to put items that are obvious in the comments section. Comments that are too long can make it harder to find the information you need.

Implementation and documentation comments are the two sorts of comments Java allows. In addition, they have a variety of purposes and a variety of formats. Let’s dig a little more into this:

JavaDoc/Documentation Feedback

• The target audience here is the codebase’s end users.
• Focusing more on the specification than the implementation is common here.
• Is typically useful regardless of the programming language.

The Block/Implementation Commentary

• The target audience here is the programmers who are currently working on the codebase.
• The specifics here are dependent on the implementation.
• Usually helpful in conjunction with the codebase

As a result, how can we use them most effectively so that they are relevant and useful?

• If we can’t understand a piece of code without comments, perhaps it’s time to rework it. Block comments should be reserved for describing complex design decisions.
• Most of our classes, interfaces, public methods, and protected methods should have JavaDoc comments.
• For readability, all comments should be properly indented.

As an example of useful documentation comments, let’s look at this one:

/**

* This method is intended to add a new address for the customer.

* However do note that it only allows a single address per zip

* code. Hence, this will override any previous address with the

* same postal code.

*

* @param address an address to be added for an existing customer

*/

/*

* This method makes use of the custom implementation of equals 

* method to avoid duplication of an address with same zip code.

*/

public addCustomerAddress(Address address) {

}

 

Logging

There is nothing more frustrating than trying to figure out what’s wrong with a piece of software that you’ve worked on for a long time. It is impossible to overstate the value of logs in development and maintenance.

 

SLF4J and Logback are only two of the many logging libraries and frameworks available in Java. However, logging best practices must be considered while using these tools because they make logging a breeze in a codebase. Well-executed logging can turn out to be a headache to maintain rather than a boon. Some of the finest practices to keep in mind:

• Avoid logging too much; instead, consider what data might be useful for troubleshooting.
• We may want to activate some log levels on production but not others, so choose your log levels carefully.
• In the log message, make sure to include all relevant contextual information.
• For faster analytics, use external tools for tracing, aggregating, and filtering log messages.

Let’s have a look at an example of descriptive logging at the appropriate level:

logger.info(String.format(“A new customer has been created with customer Id: %s”, id));

 

Is That All There Is to It?

We have to be aware of and concerned about many more code formatting conventions than those mentioned in the preceding section. Over time, many additional best practices have been accrued for the advantage of understandable and maintainable code.

Over time, we may have come across them as amusing acronyms. A single principle or a set of principles can be used to help us develop better code. However, it is vital to remember that we should not just follow all of them. If the codebase is large and complex, the benefit they bring is usually proportional. Any new principle must be tested against our existing code. We also need to stick to our guns and not waver in our commitments.

 

SOLID

For building intelligible and maintainable software, SOLID is an acronym that pulls from the five principles it sets forth:

 

• There should be only one task for each interface, class, or method that we create. Ideally, it should focus on a single task and perform it well. Smaller methods and classes that can be tested are a result of this.
• As a rule of thumb, the code that we write should be extensible but not editable. Put another way; classes should be written so that they don’t need to be changed. However, it should be able to be inherited or recombined.
• According to the Substitution Principle, Liskov Subclasses and derived classes should be interchangeable with their parent or base class. Reusability is enhanced by minimizing the amount of coupling in the codebase.
• If our class implements an interface, it will have the same behavior as if it didn’t. However, a class should not have to implement methods that it doesn’t need to be able to use. This necessitates the development of interfaces that are more nimble and narrowly focused.
• According to the Dependency Inversion Principle, class dependencies should only be based on abstractions, not their specific implementations. A class should not be responsible for producing instances of its dependents. Instead, these dependencies should be injected directly into the class.

 

DRY & KISS

“Don’t Repeat Yourself” is the acronym for DRY. Code should not be reused across the software, according to this notion. In order to reduce waste and promote reusability, this idea was developed. We should be careful, though, not to take this too literally. A small amount of duplication can enhance the readability and maintainability of software.

Keeping things simple is the KISS motto. Keeping the code as basic as possible is one of the tenets of this philosophy. This makes it simple to understand and maintain in the long run. Keeping our classes and methods to a manageable size is a good way to ensure that our code is way easier to read and maintain.

 

TDD

“Test-Driven Development” is the acronym for this method of software development. Code should only be written if an automated test fails, according to this programming technique. As a result, we must begin by developing automated testing. Automated unit tests can be written in Java using frameworks such as JUnit and TestNG.

Such a practice has enormous advantages. Software that always performs as intended is the result of this approach. The progressive addition of working code in small bits is how we always begin. As a bonus, we only add code when the new or previous tests fail. Because of this, reusability is also a result.

 

Helpful Tools

Personal habits are equally as important as concepts and procedures when writing code. As we learn and adapt, we tend to become better developers in the process. However, in order to preserve uniformity across a huge team, we must also put enforcement to the test. In the past, code reviews were a fantastic technique to ensure that the code was consistent and to assist engineers in learning through constructive criticism.

These concepts and best practices don’t have to be validated by hand during code reviews. Some quality checks can be automated so that the code always meets a given standard. Freddy Guime, from Java OffHeap, discusses this idea.

At least some of these responsibilities can be taken away from code reviewers by using various tools available in the Java ecosystem. Let’s take a glance at some of these tools.

• Code Formatting: Most prominent Java code editors, such as Eclipse and IntelliJ, provide built-in code formatting features. If we don’t want to employ the default formatting rules, we can alter or replace them. Many structural coding conventions are addressed here.
• SonarQube, Checkstyle, PMD, and SpotBugs are just some Java static code analysis tools available. You can use the rules as-is or modify them to fit your needs for a particular project. It smells like name conflicts, and resource leakage is easy to spot thanks to these tools.

 

Conclusion

In this article, we’ve gone through the significance of clean coding concepts and the qualities that clean code demonstrates. We saw how to use some of these concepts in practice, which were created in Java. We also addressed some best practices that help to keep the code readable and manageable over time. Finally, we explored some of the tools available to help us in this attempt.

To summarize, it’s critical to understand that all of these principles and techniques are in place to help us write cleaner code. This is a more subjective concept and, consequently, must be judged contextually.

While there are different rules available to accept, we must be aware of our maturity, culture, and necessities. We may need to customize or, for that matter, develop a new set of regulations entirely. But, whatever the situation may be, it’s crucial to remain consistent across the organization to enjoy the rewards.