Java Code Style Guide: Common Formatting Conventions Explained
Java code style is not just about aesthetics. Consistent formatting reduces cognitive load, prevents merge conflicts, and catches bugs before they happen. This guide covers the conventions most Java developers agree on, why they exist, and the few cases where breaking them is justified.
Indentation: The Foundation
Four spaces per indentation level is the near-universal standard in Java. Not two spaces (Python style). Not tabs (though some older codebases still use them). The Oracle Java Code Conventions specify four spaces, and every major open-source Java project follows this rule.
Why four spaces? Research on code readability shows that four-space indentation provides enough visual separation between nesting levels without pushing deeply nested code too far to the right. Two spaces are harder to scan at a glance. Eight spaces (the old Sun Microsystems standard for C) waste horizontal space on modern widescreen monitors.
Tabs vs spaces: The Java community has largely settled on spaces. Tabs cause alignment problems when different tools display them at different widths. A file that looks perfectly aligned in your editor with 4-width tabs becomes a mess in a colleague's editor with 8-width tabs. Use spaces.
Brace Placement: KandR Style
Java uses the Kernighan and Ritchie (KandR) brace style: the opening brace goes on the same line as the statement that introduces the block. Example:
public void process(String input) {
if (input == null) {
return;
}
doWork(input);
}Do not put the opening brace on its own line (Allman style). While Allman style is valid Java and popular in C# and some C++ communities, it is rare in Java. Following the dominant convention makes your code easier for other Java developers to read.
Naming Conventions
- Classes and interfaces: PascalCase (HttpClient, UserRepository). Nouns or noun phrases.
- Methods: camelCase (getUserName, processRequest). Verbs or verb phrases.
- Variables: camelCase (userCount, isActive). Short but descriptive.
- Constants: UPPER_SNAKE_CASE (MAX_RETRIES, DEFAULT_TIMEOUT). Use static final.
- Packages: lowercase, reversed domain (com.example.project). No underscores.
Single-letter variable names are acceptable only in loop counters (i, j, k) and catch block parameters (e). Never in method signatures or class fields.
Imports: Keep Them Organized
Avoid wildcard imports (import java.util.*). They pollute the namespace and make it unclear which classes are actually used. IDEs often collapse multiple imports from the same package into a wildcard by default; disable this setting.
Import ordering (standard convention):
- java.* packages
- javax.* packages
- Third-party libraries (org.apache.*, com.google.*)
- Project-specific packages
Within each group, sort alphabetically. Most IDEs do this automatically, and the online formatter handles it too.
Line Length and Wrapping
The traditional 80-character limit comes from VT100 terminal width. Modern Java projects typically use 120 or 140 characters. Pick one and apply it consistently. When a line exceeds the limit, break it at a logical point: after a comma in a long parameter list, before a method call in a chained expression, or after an operator in a long expression.
Comments and Documentation
Javadoc comments (/** ... */) go on all public methods and classes. Describe what the method does, not how it does it. Include @param and @return tags. For internal comments (// or /* */), explain why the code does something non-obvious, not what it does (the code already shows what).
Format your Java code against these conventions using the Java Formatter.