Stage 5·Software Craftsmanship

Java Coding Conventions

Naming, formatting, package layout, Javadoc, and idiomatic-Java checklists.

12 min readBeginner

On this page

Consistent code is professional code. Coding conventions are the shared rules that make Java from thousands of different developers look and feel like it was written by one careful team. They reduce friction, prevent bugs, and make reviews smoother.

Naming conventions

Java has strong, near-universal naming rules. Follow them and your code instantly looks native:

Element	Convention	Example
Class / Interface	`PascalCase` (noun)	`OrderService`, `Payable`
Method / variable	`camelCase` (verb for methods)	`calculateTotal`, `userName`
Constant	`UPPER_SNAKE_CASE`	`MAX_RETRIES`
Package	all lowercase	`com.myapp.orders`
Type parameter	single capital letter	`T`, `E`, `K`, `V`

public class ShoppingCart {                 // PascalCase class
    private static final int MAX_ITEMS = 50; // constant
    private List<Item> items;                // camelCase field

    public double calculateTotal() {         // camelCase verb method
        return items.stream().mapToDouble(Item::price).sum();
    }
}

Names should reveal intent

calculateTotal() tells you exactly what it does; calc() or doIt() don't. Booleans read as yes/no questions: isEmpty, hasNext, canEdit. Good names are the cheapest documentation you'll ever write.

Formatting

Indentation: consistent (commonly 4 spaces). Never mix tabs and spaces.
Braces: opening brace on the same line (if (x) {), the "K&R" style Java favors.
Line length: keep lines readable (around 100–120 characters).
One statement per line; blank lines to separate logical blocks.

Let a formatter do it

Don't argue about formatting - automate it. Tools like google-java-format, Spotless, or your IDE's formatter apply a consistent style on save. The whole team's code looks identical, and you never think about it again.

Package structure

Organize code into packages by feature or layer, using reverse-domain naming:

com.myapp
├── order        (feature)
│   ├── OrderService.java
│   ├── OrderController.java
│   └── OrderRepository.java
├── payment
└── user

Grouping by feature (all order-related classes together) usually scales better than grouping by technical layer (all controllers together).

Javadoc: documenting the public API

Javadoc comments (/** ... */) document classes and public methods, and generate browsable HTML docs:

/**
 * Calculates the total price of all items, including tax.
 *
 * @param taxRate the tax rate as a fraction (e.g. 0.2 for 20%)
 * @return the total price in cents
 */
public long calculateTotal(double taxRate) { ... }

Document the public contract, not the obvious

Write Javadoc for public APIs others will use - what a method does, its parameters, return value, and any exceptions. Skip Javadoc that merely restates an obvious method name; clear code needs less of it.

Idiomatic Java checklist

Small habits that mark experienced Java developers:

Declare variables by their interface: List<String> x = new ArrayList<>();
Use enhanced for and streams over manual index loops where they read clearer.
Prefer final for fields and variables that shouldn't change.
Compare objects with .equals(), never ==.
Use Optional for maybe-absent return values, not null.
Keep methods short and classes cohesive.
Handle exceptions meaningfully - never swallow them silently.

Quick check

Which name correctly follows Java conventions for a constant?

Key takeaways

Follow Java naming: PascalCase classes, camelCase methods/variables, UPPER_SNAKE_CASE constants, lowercase packages.
Keep formatting consistent and automate it with a formatter (Spotless, google-java-format).
Organize packages by feature using reverse-domain names.
Write Javadoc for public APIs - the contract others rely on - not for obvious code.
Idiomatic Java: program to interfaces, use streams/for-each, prefer final, compare with .equals(), avoid null via Optional.

Stage 5 complete! You now write not just working code but well-crafted code. Stage 6 turns you into a professional: databases, testing, build tools, frameworks, and system design.