Opinionated Java Style Guide for Teams by @tusharvjoshi
If you are looking for an opinionated style guide for syntax, conventions, and structuring Java code, then step right in. This way of writing style guide is heavily inspired from @john_papa.
The source file name consists of the case-sensitive name of the top-level class it contains (of which there is exactly one), plus the .java extension.
? Why: As dectated by Java compiler rules.
? Why: Only one top level class is recommended and that class name should be the file name
Source files are encoded in UTF-8.
? Why: This will support cross platform and cross locale source
? How: Modern IDEs have support for the encoding as global or project settings
? Same as: Google Style Guide1 section 2.2
Order of the elements in a Java source file shall be
- License section
- package declaration
- import statements
- Functional comment for top level class
- Class declaration
- Constants
File shall start with a license statement. For open source projects as well as commercial projects there is usually a license which comes here in a multiline comment.
The package statement is not line-wrapped. The column limit does not apply to package statements.
- no wildcard imports in static or normal imports
- no import statements (IDE provides feature of fixing import statement which shall be used before committing the source file)
- Import statements are not line-wrapped. The column limit does not apply to import statements.
There shall be a functional Javadoc comment for the top level class mentioning the usage of the class. Main dependencies and calling mechanism which is not obviious from the source.
Packages shall be named starting with the reverse company name for example com.company.project.module
? Why: To avoid namespace collision.
Package names shall be all small letters and single words separated by dots.
For example:
package com.company.product.module;Constants shall be kept in the class nearer to the functionality. They should not be kept in a common constant class.
? Why: Keeping constants in one common constants class is not maintainable. When there is a change in any of the constants it introduces potential regression for all the areas where this Constants class is used.
? Other references: Stackoverflow discussion
/* avoid */
public class Constants {
public static final String RATEOFINTEREST_TYPE = "Simple";
public static final String WELCOME_MESSAGE = "Welcome";
}/* recommended */
public class InterestCalculator {
public static final String RATEOFINTEREST_TYPE = "Simple";
/* other code */
}
public class WelcomeView {
public static final String WELCOME_MESSAGE = "Welcome";
}Each top-level class resides in a source file of its own.
The ordering of the members of a class can have a great effect on learnability, but there is no single correct recipe for how to do it. Different classes may order their members differently.
What is important is that each class order its members in some logical order, which its maintainer could explain if asked. For example, new methods are not just habitually added to the end of the class, as that would yield "chronological by date added" ordering, which is not a logical ordering.
These references are the starting points of this style guide. Many more additions and changes are done on these initial styles. Newly revealed patterns like clean code by Robert C Martin have influenced many of the styles in this list.