Writing Readable and Maintainable Code — Java

Chamith Madusanka
Oct 21 · 6 min read
Image for post
Image for post

Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live — John Woods

Writing clean code is not easy. It must be readable and maintainable. Writing clean code is not a process that we can achieve very quickly. It’s a continuous process, practically a daily effort. So let’s start…

1. Proper Naming

Naming is on of the most important aspect of coding. But somehow most of developers underestimate the importance of proper naming in the code. Developers spend most of their time reading code instead of writing. Thinking what is the purpose of this class, what kind of data containing in this field and what this method really does.

  • Class name should be a noun. When you create a instance from a class it should be a thing that physically exists. It can also be abstract thing. Always try to make it as noun.
  • Class name should be specific. If not every time we have to go inside the class to see what’s inside. E.g. Suppose you have CommonUtils.java class containing random number generating method, String split method. Better to make both methods to two separate classes and name as StringUtils.java, NumberUtils.java.
  • Never a single letter.
  • Always specific.
  • Ideally 1–2 words.
  • Boolean should prefix with is, has, can, should( isValid, isActive, hasLicense, canEvaluate, shouldAbort).
  • Use camelCase.
  • Use ALL_CAPS with underscores for constants.
  • Functionality fully understandable from the name.
  • Should name like Verb (Do what?) + Noun (To what?). But better be specific. e.g : setCustomerName, calculatePrice, validateUserDetails
  • Do not use and, or, if in method names.

2. Implementing Methods

When implementing method we should carefully take a look on what not to return, method parameters, fail fast & return early, conditionals, apply Single responsibility principle (SRP) etc.

  • Method can return primitives, objects or null. Avoid returning null as much as possible. when we return null if caller doesn’t know about it will hit a NullPointerException. If caller does know about null have to add extra checks. This extra condition here adds cyclomatic complexity and every time the method calls caller has to add null checks.
  • Method should only do one thing. That’s how we apply SRP(Single Responsibility Principle) to methods
  • Avoid returning special codes (-1, 0, 1 and other) from a method. It will force client code to check for magic numbers.
  • Always try to have 0–3 arguments in a method. More than that will indicate your method needs refactoring. If method takes too many primitive types, pass a single object.
  • Put magic numbers as parameters only if a method accepts one argument and method name suggests what method does. e.g. nowPlusWeeks(int weeks), nowPlusDays(int days). If not it’s very difficult to identify what method does without looking inside. e.g. nowPlusTime(int months, int weeks, int days)
Image for post
Image for post
nowPlusTime() with magic numbers as parameters (Not good)
Image for post
Image for post
Understandable methods even with magic number parameters
  • Avoid flag (Boolean) arguments as method parameters. Flag arguments complicates the signature of the method, loudly proclaiming that method does more than one thing. If we have a method with sendNotification(content, isSms) we can split it to two methods as sendSms(content), sendEmail(content)
Image for post
Image for post
Method with flag argument
Image for post
Image for post
Flag argument method split into two methods
  • Fail fast and return early. Immediately report any failure and let the program fail. If you have arithmetic calculations inside a method, check at top of the method for certain conditions to avoid arithmetic exceptions and throw IllegalArgumentException. Therefore we can throw the exception early before it reach the logic.
Image for post
Image for post
Throw exception early
  • Multiple if statements lead to high cyclomatic complexity. It’s very difficult to keep all those conditions in head while reading the code. To avoid this we can check simple conditions first and return immediately. Now you can see conditions and the return statements are in the same line. If you have argument values that are valid but they are logically allow you to stop execution early, then evaluate these first and exit the function right away.
Image for post
Image for post
With multiple if blocks
Image for post
Image for post
Refactored with return early
  • DRY — Don’t Repeat Yourself. If you have repeating code in methods, put those into a single method.
  • Avoid complex conditionals. Just extract complex logical conditions to a separate method that sounds like Boolean question and return a Boolean value.
Image for post
Image for post
Complex if condition, difficult to under
Image for post
Image for post
Condition moved to a separate method with understandable name
  • Avoid nested ternary expression. Instead put those in separate if statements for readable code.

3. Exception Handling

  • Don’t catch the top level throwable because you might catch errors , such as out of memory error or internal error.
  • Try to avoid catching the general exception because you might catch runtime exceptions that shouldn’t be caught such as NullPointer. You should use multiple catch blocks to cater this issue. Then you can show specific exception messages as well. But after Java 7 we can handle this by one line and it’s easy. But the downside is we can’t show specific exception messages.
Image for post
Image for post
Catching general exception is not good
Image for post
Image for post
Better way to catch multiple exception
Image for post
Image for post
Easier and better way to catch multiple exception
  • Don’t handle NullPointerException. NullPointerException is a result of programing error. If we handle NullPointerException then we cover up our own programming errors.
  • Don’t put empty catch blocks.
  • Don’t put only logs in catch blocks.
  • In catch block we should log the error using any logger framework and throw the exception with a informative message.
  • Avoid methods that throw exceptions in finally block.

4. Class Organization

  • We should only put methods that are specific to the particular class. That’s how we apply SRP(Single Responsibility Principle) to classes. Should put functionally and logically working things together.
Image for post
Image for post
Few unrelated methods in Order class
Image for post
Image for post
Unrelated methods are moved to separate classes
  • Always try to program to an interface. If not for a single change you have to go through each and every class to change.
  • Put inter-related methods one after the other for better readability.
Image for post
Image for post
Proximity rule

5. Writing Comments

  • Don’t put redundant comments if a method or a variable says what it does.
  • Don’t keep commented out code.
  • Use JavaDoc comments as necessary.
  • Don’t put comments on getters and setters.

Always code with static code analyzer in your IDE. It will give you a better code review on the code before submitting it. (SonarLint, FindBugs)

Thank you for reading this post. If you like this post, give a Cheer!!!

Happy CLEAN Coding ❤

The Startup

Medium's largest active publication, followed by +731K people. Follow to join our community.

Chamith Madusanka

Written by

Senior Full-Stack Engineer | Java | Spring boot | ReactJs | NodeJs | NestJs | Microservices

The Startup

Medium's largest active publication, followed by +731K people. Follow to join our community.

Chamith Madusanka

Written by

Senior Full-Stack Engineer | Java | Spring boot | ReactJs | NodeJs | NestJs | Microservices

The Startup

Medium's largest active publication, followed by +731K people. Follow to join our community.

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store