Sitemap
Oluwatunmibi Favour

Oluwatunmibi Favour

Software Engineer. I enjoy documenting my learning journey and writing on topics I'm passionate about.

Writing Clean Code with Java

4 min readMar 10, 2025

--

Press enter or click to view image in full size
Writing Clean Code with Java

Java has been in existence for over 20 years and is still one of the most widely used programming languages today. Why? It is object-oriented, platform-independent, and has a massive ecosystem, but one of the things that stands out to me about Java is how its syntax and structure encourage writing clean and maintainable code. As software developers, we all know how important that is — especially when your code is running in production.

Clean code is not all about writing code that looks neat (even though that’s a plus). Rather, it’s about writing code that’s easy to read, understand, and maintain. It’s about saving your future self and/or your team from the stress of deciphering a tangled mess when requirements change, or bugs pop up. As Robert C. Martin, the author of Clean Code, puts it:

“Clean code is code that has been taken care of. Someone has taken the time to keep it simple and orderly.”

In this article, using a movie management REST API I built using SpringBoot, I’m going to walk you through how I applied clean code principles in Java and how you can too. No matter your level of expertise in software development, I hope you’re able to get some practical takeaways from this to apply to your own projects.

Organizing the Codebase

The first step is organization. A well-structured codebase is like a well-organized toolbox — you know exactly where everything is, and you can find what you need without wasting time. For my movie API, I divided the code into clear, logical layers:

- Entities: They represent the core data models, like User and Movie. Each entity is simple and focused, sticking to the Single Responsibility Principle (SRP).
- Repositories: These handle database interactions. By keeping data access logic separate, I made sure the service layer could focus purely on business logic.
- Services: This is where the core logic lives. I used interfaces (like MovieService) and their implementations (MovieServiceImpl) to keep things flexible and testable.
- Controllers: These handle incoming HTTP requests, delegate work to the service layer, and return responses. They’re the gatekeepers of the API.
- DTOs (Data Transfer Objects): These act as messengers between layers, carrying data without exposing the internal structure of entities.
- Utilities: Helper classes like AuthResponse and LoginRequest live here, keeping the code DRY (Don’t Repeat Yourself).
- Exceptions: Custom exceptions like MovieNotFoundException and TokenExpiredException make error handling more specific and meaningful.

Get Oluwatunmibi Favour’s stories in your inbox

Join Medium for free to get updates from this writer.

Here’s a snippet of what the folder structure looks like:

com/movieflix/movieapi/
├── auth/
│ ├── config/
│ ├── entities/
│ ├── repositories/
│ ├── services/
│ └── utils/
├── controllers/
├── dto/
├── entities/
├── exceptions/
├── repositories/
├── services/
└── MovieApiApplication.java

This structure isn’t just about aesthetics — it’s about making the codebase intuitive. Even if someone else picks up this project, they’ll know exactly where to find what they need.

Principles I Followed

While building this API, I kept a few key principles in mind to ensure the code stayed clean and maintainable:

  1. Single Responsibility Principle (SRP): Every class and method should have one job. For example, the MovieService class handles movie-related logic, and nothing else. This makes the code easier to test, debug, and extend. Here is what my MovieService.java file looks like:
package com.movieflix.movieapi.services;

import com.movieflix.movieapi.dto.MovieDto;
import com.movieflix.movieapi.dto.MoviePageResponse;
import org.springframework.web.multipart.MultipartFile;

import java.io.IOException;
import java.util.List;

public interface MovieService {

MovieDto addMovie(MovieDto movieDto, MultipartFile file) throws IOException;

MovieDto getMovie(Integer movieId);

List<MovieDto> getAllMovies();

MovieDto updateMovie(Integer movieId, MovieDto movieDto, MultipartFile file) throws IOException;

String deleteMovie(Integer movieId) throws IOException;

MoviePageResponse getAllMoviesWithPagination(Integer pageNumber, Integer pageSize);

MoviePageResponse getAllMoviesWithPaginationAndSorting(Integer pageNumber, Integer pageSize, String sortBy, String dir);
}

2. Don’t Repeat Yourself (DRY): Repeated code is a breeding ground for bugs and inconsistencies. I created reusable utility methods and DTOs to keep things DRY.

3. Meaningful Naming: A well-named class or method is like a good road sign — it tells you exactly where you’re going. Instead of vague names like process() or handle(), I used descriptive names like getAllMovies() and generateOtpToken().

4. Separation of Concerns: Each layer of the application has a clear purpose. Controllers handle requests, services manage business logic, and repositories deal with data access. This separation makes the codebase easier to navigate and maintain.

5. Error Handling: I created custom exceptions like MovieNotFoundException and TokenExpiredException to make error messages more specific and actionable. This not only improves debugging but also makes the API more user-friendly.

Why Clean Code Matters

Clean code isn’t just a nice-to-have — it’s a necessity. It reduces technical debt, speeds up development, and makes collaboration smoother. It’s also a gift to your future self. Trust me, there’s nothing worse than revisiting old code and realizing you have no idea what it does.

So, the next time you write code, ask yourself: Is this clean? Is it maintainable? If I didn’t write this, would I be able to understand it? If the answer is no, take a step back and refactor. Your future self — and your team — will thank you.

Final Thoughts

Writing clean code is a skill that takes time and practice, but it’s worth the effort. By organizing your codebase, and following principles like SRP and DRY, you can create code that’s not just functional but also maintainable. That’s what makes the difference between a regular developer and an outstanding one.

You can check out the rest of the code for the movie management API here.

So, what’s your approach to writing clean code? I’d love to hear your thoughts and tips — let’s keep the conversation going!

--

--

Oluwatunmibi Favour
Oluwatunmibi Favour