java-clean-code

Java Clean Code

Overview

20 high-ROI rules for Java, with topic references for depth. Same checklist for writing, reviewing, and refactoring.

When to Apply

Writing, reviewing, or refactoring Java classes/methods/endpoints/services; or answering principle questions about Java design.

Skip when: trivial edits, build/config files, non-Java code, or when the user opts out.

The Top 20 Rules

Each rule links to a reference file for depth. A subset keeps a Check hint where the name alone is ambiguous.

1. Names reveal intent. naming
2. Functions do one thing. functions
3. ≤3 arguments per function. functions
4. No flag (boolean) arguments. functions
5. Command-Query Separation. Method either does OR answers, not both. functions
6. One abstraction level per function. functions
7. Stepdown rule (newspaper metaphor). High-level entry points at top, helpers below. formatting
8. No hidden side effects. functions
9. Exceptions over error codes. functions
10. Law of Demeter — no trainwrecks. No a.getB().getC().doD() chains on objects (chains on data structures OK). objects-and-data
11. Objects hide data; expose behavior. objects-and-data
12. Single Responsibility Principle. solid
13. DRY. functions
14. Consistent vocabulary. naming
15. Write the test first (TDD). testing
16. Tests are FIRST. Fast, Independent, Repeatable, Self-validating, Timely. testing
17. No magic numbers or unexplained literals. naming
18. Early returns over deep nesting. Max 2 levels of nesting inside a function. functions
19. Constructor injection (DIP). @Autowired field injection is a smell; inject via final constructor params. solid
20. Comments earn their keep. Explain WHY, not WHAT. comments

Workflow

Writing: (1) Name the behavior — if you can't, the design isn't ready. (2) Write the failing test (JUnit 5). (3) Implement minimally, rules 2–6 in mind. (4) Self-check with the checklist below.

Reviewing: (1) Cite each violation by rule name (Demeter, SRP, DIP — never bare "R10") + file:line. (2) Prioritize severity — SRP/Demeter/testing gaps outrank naming nits. (3) Diff-style fixes, each naming the rule. (4) Open references/*.md for rationale.

References

Each rule links inline to the topic file. Additional depth: smells, architecture, concurrency, craftsmanship, creating-objects, generics, lambdas-and-streams, exceptions.

Pre-delivery checklist

• Verb+noun names; no flags; ≤3 args.
• Tests exist, run fast, written first.

Rationalizations

Excuse	Counter
"One more arg"	Args/Flags: extract a record.
"Use Lombok @Data"	DIP: write the explicit constructor.
"Fine for a demo"	SRP holds under pressure.
"Review with bare numbers (R10)"	Cite the rule name + references/*.md.

Violating the letter of a rule is violating its spirit. Pressure (time, demo, sunk cost) does not suspend the rules — it makes them more valuable.