The Java reordering tool I wanted for years, so I finally built it

For years, I wanted one simple thing in Java projects: a reliable way to keep class members ordered and formatted consistently. Fields, constructors, methods, accessors, nested types. Not manually. Not by a team convention written in a wiki. Not by asking everyone to remember the right IDE action before committing. A real tool. Something I could run locally, wire into Maven, and enforce in CI pipeline.

I kept thinking this should already exist. The problem felt too common to be mine alone. Every Java team eventually deals with source layout, member ordering, formatting noise, and code review readability. To me, this looked like an obvious missing tool: take a Java class, reorder it safely, format the result, and make the same rule runnable from the command line, Maven, or CI.

The important part was that the rule should not depend on a developer’s IDE, local machine, personal settings, or willingness to run the right action. It should be part of the project configuration itself, fixed in the build and enforced by the pipeline quality gates.

And yet, somehow, I never saw this simple and obvious piece of tooling become a normal part of the Java ecosystem.

So I stopped assuming that someone else had already solved it and built it myself. The result is JHarmonizer, an open-source Java source harmonization tool.

But before talking about the tool, I want to explain the pain that led to it.

Code conventions are not just about pretty code

Code conventions are often discussed as if they are mostly about aesthetics: spaces, braces, blank lines, import order, line wrapping, method order, field order, etc. And yes, pretty code is nice, but that is not the main point.

The main consumer of source code is not the computer or the compiler. The main consumer is another developer: the person who reviews the change, debugs it six months later, extends it next year, or tries to understand why something was written this way.

That is why formatting, ordering, and structure conventions matter. They create shared expectations. When a team agrees on a consistent structure, developers stop spending mental energy on layout. They know where to look for fields, constructors, lifecycle methods, public API methods, private helpers, accessors, and nested types. This makes code easier to scan. It makes similar classes easier to compare. It makes code reviews faster because reviewers do not need to relearn the structure of every class from scratch.

Another real enemy is noisy diffs

In a team, inconsistent formatting and member ordering create a very practical problem: noisy diffs. A developer may touch one method, but their IDE reformats a file differently. Another developer may move a helper method closer to the code they were editing. Someone else may sort methods alphabetically. Someone may keep getters and setters together. Someone may not. And if your first reaction is “just document the convention and agree on it,” that may work in a small stable team, but in large enterprise projects with changing teams and different local setups, convention by communication quickly becomes unreliable.

The result is a pull request or merge request where the meaningful change may be only a few lines, while most of the diff is just reformatted code, moved methods, reordered fields, or import cleanup. That is not a healthy review process. The reviewer is forced to dig for the real behavior change inside a pile of layout noise. It is tiring, slow, and it directly hurts review quality.

Good tooling should separate these concerns. If the project has a canonical representation of source code, every developer can automatically bring the file back to that representation before review. The diff becomes cleaner. The reviewer focuses only on actual behavior changes. That is the real value of code style automation.

Why this gets worse in larger teams

In a small project, informal rules can sometimes work. In a larger team, they stop scaling.

Different developers may use different IDEs, different formatter settings, different habits, and different levels of discipline. Some changes may happen through VS Code, Eclipse, a web editor, GitHub/GitLab UI, scripts, or automated tools.

At that point, “please remember to arrange the class correctly” is not a process. It is wishful thinking. The convention has to be executable. It should not live only in a wiki page. It should not depend only on one developer's IDE profile. It should be something the project can apply automatically and verify in CI. That is the difference between a preference and a quality gate.

What I wanted instead

I wanted the workflow to be boring:

1. write code;
2. run the tool;
3. get the canonical project structure;
4. review only the meaningful diff.

For local development, the tool should be able to rewrite files automatically. For CI, it should be able to check that files are already harmonized and fail the build if they are not. Same input. Same output. Same rule for everyone. No dependency on a specific IDE. No “please remember to run this manually.” No formatting and layout noise mixed into semantic changes.

Formatters solve only part of the problem

Of course, modern IDEs already have built-in Java formatters. They are useful, and they are usually good enough for local development. But in practice, IDE formatters often remain too dependent on local settings, project profiles, personal preferences, and sometimes even the original layout created by the developer. That is not enough if the goal is a canonical representation of the source code.

For strict and reproducible Java formatting, the strongest tools I found were google-java-format and palantir-java-format. They are intentionally opinionated: instead of preserving too much personal layout style, they produce a predictable result. They also have IDE integrations, so developers can use them locally, but their real strength is that they can be wired into Maven or Gradle. That means formatting can be applied and checked outside the developer’s IDE, independently of local environment, personal preferences, or machine-specific setup. This is exactly the kind of behavior I wanted: not only “my IDE formats this file somehow,” but “the project has one formatting rule, and the build can protect the repository from unformatted code.”

But good formatting is still not enough. Formatting handles whitespace, indentation, line wrapping, imports, and syntax layout. It can make a method body look clean, normalize blank lines, and remove import noise. What it usually does not solve is source structure.

A formatter does not normally decide where fields, constructors, methods, accessors, and nested types should live inside a class. It does not restore a project-specific class layout. It does not know that constants should be grouped first, constructors should stay together, public API methods should come before private helpers, accessors should remain near each other, or test classes may need a different structure than production classes.

And this matters because bad structure can destroy most of the benefit of good formatting. Even if every line is perfectly formatted, a developer can still move methods around according to their own habits, mix accessors with business logic, separate related members, or apply a completely different mental convention to the same kind of class.

So the order matters: first restore the expected structure, then apply formatting. That is the layer I kept missing.

IDE rearrangement helps, but only locally

IntelliJ IDEA and Eclipse have code rearrangement features, and they are actually useful. They can arrange members by different rules, and for local development that may be enough. But this is still an IDE-level workflow.

It only works reliably if everyone:

• uses the same IDE;
• has the same settings;
• has the same project configuration;
• remembers to run the same action;
• never edits code through another environment.

That is not how real teams always work. IDE features are good for local productivity. But they are not a reliable team-wide quality gate by themselves. For that, the rule has to live in the build pipeline.

Checkstyle can check, but it cannot rewrite

Checkstyle can help with coding conventions, and it is still useful for many broader rules. But for member ordering, it has two important limitations.

First, it reports violations. It does not rewrite the source code. So if the order is wrong, the developer still has to fix it somehow, at best by running the IDE’s rearrangement action.

Second, safe ordering is harder than it looks. Java declarations are not always independent. One constant may depend on another constant, a field initializer may depend on a field declared above it, and static or instance initialization blocks may rely on members that already exist earlier in the class.

For example, this order is safe:

private static final int DEFAULT_TIMEOUT_SECONDS = 30;
private static final int API_REQUEST_TIMEOUT_SECONDS = DEFAULT_TIMEOUT_SECONDS * 2;

But if a tool blindly sorts fields alphabetically, it may accidentally produce this:

private static final int API_REQUEST_TIMEOUT_SECONDS = DEFAULT_TIMEOUT_SECONDS * 2;
private static final int DEFAULT_TIMEOUT_SECONDS = 30;

Now the code structure changed in a way that is not just cosmetic. API_REQUEST_TIMEOUT_SECONDS depends on DEFAULT_TIMEOUT_SECONDS, so the base constant must stay above the derived one. This is why member ordering cannot be treated as simple text sorting. A tool has to understand declaration-order dependencies and avoid creating an order that conflicts with valid Java code.

That is exactly where a simple checker is not enough.

So I built JHarmonizer

JHarmonizer is an open-source Java source harmonization tool.

It is designed to reorder and format Java source code in a reproducible way.

It can:

• reorder Java class members while respecting declaration-order dependencies;
• keep accessors together;
• apply different ordering strategies for different kinds of types, such as interfaces, DTOs, test classes, utility classes or regular production classes;
• format the reordered result with Palantir Java Format;
• run from Maven or the command line in auto-fix mode to rewrite source files automatically;
• run in check mode as a CI quality gate.

The goal is not just “sort methods alphabetically.” The goal is to make Java class structure enforceable from the build.

What JHarmonizer does

At a high level, JHarmonizer takes Java source code, analyzes it, applies ordering rules, reconstructs the source, and formats the result. The important part is that member ordering is not treated as a purely cosmetic operation. The tool has to respect cases where declaration order matters.

That is why JHarmonizer does not try to be only a formatter. It is more of a source harmonization tool: formatting plus structure.

Where it fits with other tools

JHarmonizer is not trying to replace the whole Java quality ecosystem. Static analyzers, bug detectors, coverage tools, architectural tests, and code review tools all solve different problems. JHarmonizer focuses on one specific layer: making Java source structure and formatting reproducible from the build.

A typical Java quality setup may include:

• Maven Enforcer for Java, Maven, and dependency rules;
• PMD for static code checks;
• CPD for duplicate code detection;
• SpotBugs for bug patterns;
• JaCoCo for coverage thresholds;
• license checks for SPDX or license headers;
• sortpom for deterministic pom.xml ordering;
• JHarmonizer for Java source ordering, formatting, and check mode.

The point is not to have one magic tool. The point is to make each part of the code quality workflow executable and reproducible.

Why quality gates matter in the age of AI

AI agents make deterministic quality gates more important, not less. They are useful for generating code, explaining code, suggesting improvements and helping with refactoring, but asking an AI agent to follow a style guide in natural language is not the same as enforcing it. It may follow the convention, partially follow it, misunderstand it, or ignore it in the next change. Like human developers, AI agents need clear boundaries, executable rules and automatic feedback.

This is especially important because there is a strong temptation to use AI for everything, including quality gates themselves. I think that is the wrong default. If a quality rule can be expressed as a deterministic algorithm, it should be enforced by deterministic code. Formatting, member ordering, import cleanup and reproducible source structure should not depend on how a model interprets a prompt today.

This is also a cost and reliability question. A deterministic formatter, sorter or checker is fast, cheap and repeatable: the same input produces the same result. Asking an AI agent to rediscover and enforce the same convention is slower, more expensive, less predictable, and still does not provide the same hard guarantee.

AI can help produce code, but the repository still needs non-negotiable gates around the result. Deterministic quality gates keep probabilistic work inside predictable boundaries and protect the main branch with rules that do not depend on prompts, context windows or interpretation.

Try it

The project is open source: https://github.com/lemon-ant/JHarmonizer

If you work on Java projects and have ever wanted class member ordering to be enforceable from Maven, CLI, or CI, it may be useful.

Use it for free, break it, criticize it, and help me improve it. I am not planning to stop here: the repository already has a broader roadmap, and there are many more Java source-structure and CI quality-gate ideas I would like to automate in the build. I hope JHarmonizer finds its users, saves someone a bit of review time, and helps teams keep their Java code cleaner, more readable, and easier to understand. I would be happy to discuss ideas, feedback, and real-world use cases.