Best practices to write a super clean and readable code.
By: Anton Smirnov
Tags: Best Practices, Clean Code, Tips And Tricks, Automation Testing, Java

“Any fool can write code that a computer can understand. Good programmers write code that humans can understand.”- Martin Fowler.

Code readability is a universal subject in the world of computer programming. It’s one of the first things we learn as developers. This article will detail the most important best practices when writing readable code.

package proj.service; /**

* Created by John Doe.

*/

//This is interface get result and do it clean DB operation.

public interface myservice extends Workers {



public int i = 0;



public abstract String getResultList();



// public abstract void openconnection();

}

Invalid package name.

Sun / Oracle recommends naming package according to a fairly pragmatic template, namely domain.company. product. module:

Naming Conventions

package site.testengineer.persistence; /**

* Created by John Doe.

*/

//This is interface get result and do it clean DB operation.

public interface myservice extends Workers {



public int i = 0;



public abstract String getResultList();



// public abstract void openconnection();

}

Automatic generation of Javadoc template.

Created by John Doe. This comment has no informational message.

You need to apply different types of comments in the right places. Make sure that you use each type of comment correctly: don’t throw comments around and don’t insert them where you shouldn’t.

Comments must be in the English language.

The contents of the JavaDoc must correspond to reality.

package site.testengineer.persistence;



/**

* Class {@code myservice} retrieves list of {@code UserAccount}'s.

* Keep in mind, the list should not be stored after sessions clean up.

*

* @author John Doe.

* @see site.testengineer.model.UserAccount.

* @since 1.01

*/

public interface myservice extends Workers {



/**

* The constant i.

*/

public int i = 0;



/**

* Gets result list.

*

* @return the result list

*/

public abstract String getResultList();



// public abstract void openconnection();

}

Uninformative name of the interface.

myservice is not written in the camelCase style, but renaming it to MyService will not solve the situation, you need to name it as correctly as possible. You must name the interface UserTransactionService, because UserAccountTransactionService is too large, and TransactionService is not informative. It should be emphasized that classes implementing this interface are obligated to conduct a transaction related to the user. Renaming the interface, class, and JavaDoc.

package site.testengineer.persistence;



/**

* Class {@code UserTransactionService} retrieves list of {@code UserAccount}'s.

* Keep in mind, the list should not be stored after sessions clean up.

*

* @author John Doe.

* @see site.testengineer.model.UserAccount;

* @since 1.01

*/

public interface UserTransactionService extends UserAccount {



/**

* The constant i.

*/

public int i = 0;



/**

* Gets result list.

*

* @return the result list

*/

public abstract String getResultList();



// public abstract void openconnection();

}

Commented out or unused code.

As we can see, someone left the openconnection() method commented out. This code is commented out, disabled, which means that if it is not documentation and it has not changed since November, it is simply garbage. You should try to remove this kind of garbage in the code.

package site.testengineer.persistence;



/**

* Class {@code UserTransactionService} retrieves list of {@code UserAccount}'s.

* Keep in mind, the list should not be stored after sessions clean up.

*

* @author John Doe.

* @see site.testengineer.model.UserAccount;

* @since 1.01

*/ public interface UserTransactionService extends UserAccount{



/**

* The constant i.

*/

public int i = 0;

/**

* Gets result list.

*

* @return the result list

*/

public abstract String getResultList();

}

Custom formatting.

Add/subtract margins and spaces to make your work as readable as possible:

Remove unnecessary lines.

Add spaces after class names.

To separate the constants from methods.

Remove the extra empty lines.

package site.testengineer.persistence;



/**

* Class {@code UserTransactionService} retrieves list of {@code UserAccount}'s.

* Keep in mind, the list should not be stored after sessions clean up.

*

* @author John Doe.

* @see site.testengineer.model.UserAccount;

* @since 1.01

*/

public interface UserTransactionService extends UserAccount {

/**

* The constant i.

*/

public int i = 0;



/**

* Gets result list.

*

* @return the result list

*/

public abstract String getResultList();

}

Constants.

I believe that constant i has three problems here:

It doesn’t start with a capital letter

It doesn’t have any meaning. This constant must be renamed to USER_INDEX or ACCOUNT_ID

or The biggest problem is that the constant doesn’t belong in the interface at all. The object-oriented design looks more refined if you use Enum classes or private class only with constants. I think it looks much more pleasant and clear.

package site.testengineer.persistence;



/**

* Class {@code UserTransactionService} retrieves list of {@code UserAccount}'s.

* Keep in mind, the list should not be stored after sessions clean up.

*

* @author John Doe.

* @see site.testengineer.model.UserAccount;

* @since 1.01

*/

public interface UserTransactionService extends UserAccount {



/**

* Gets result list.

*

* @return the result list

*/

public abstract String getResultList();

}

Unnecessary elements.

There is no point in writing public abstract if by default any method in the public abstract interface is used.

package site.testengineer.persistence;



/**

* Class {@code UserTransactionService} retrieves list of {@code UserAccount}'s.

* Keep in mind, the list should not be stored after sessions clean up.

*

* @author John Doe.

* @see site.testengineer.model.UserAccount;

* @since 1.01

*/

public interface UserTransactionService extends UserAccount {



/**

* Gets result list.

*

* @return the result list

*/

String getResultList();

}

Imperfect architecture.

You can believe in the author of the class and imagine that it returns a list of UserAccount’s as serialized XML/JSON in String, But it is better to use List<UserAccount> instead of String. The method must also be renamed. The name of the getResultList() method is too abstract.

package site.testengineer.persistence;



/**

* Class {@code UserTransactionService} retrieves list of {@code UserAccount}'s.

* Keep in mind, the list should not be stored after sessions clean up.

*

* @author John Doe.

* @see site.testengineer.model.UserAccount;

* @since 1.01

*/

public interface UserTransactionService extends UserAccount {



/**

* Gets result list.

*

* @return the result list

*/

List<UserAccount> getUserAccounts();

}

Extended documentation.

We need information about what the getUserAccounts() method does and what it specifically returns. The class can only describe an approximate scenario of its use, so what is currently in the header should smoothly move to the JavaDoc of the method, and the service itself should be described from the side of the general functionality.

package site.testengineer.persistence;



/**

* Class {@code UserTransactionService} is a specific type of <i>User</i> transactional service.

* This service is able to retrieve user data since is has {@code UserAccount}.

*

* @author John Doe.

* @see site.testengineer.model.UserAccount

* @since 1.01

*/

public interface UserTransactionService extends UserAccount {



/**

* Returns list of {@code UserAccount}'s.

* Keep in mind, the list should not be stored after sessions clean up.

*

* @return list of user accounts

* @see site.testengineer.model.UserAccount

*/

List<UserAccount> getUserAccounts();

}

In this article, I tried to improve the quality of the code to a more sane version. Of course, this is just an example, and it is not so easy to remove/redo a lot in the project. I have fulfilled my main mission: you need to take responsibility for what you write every day. A lot depends on it. I hope you will take note of most of the possible approaches described above.