Skip to content

Latest commit

 

History

History
165 lines (105 loc) · 5.46 KB

README.md

File metadata and controls

165 lines (105 loc) · 5.46 KB
Raw

Java Style Guide

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.

Table of Contents

  1. Source File Structure
    1. File Name
    2. File encoding
    3. Order of elements
  2. Packages
  3. Constants
  4. Variables
  5. Classes
  6. Functions
  7. Comments
  8. References

Source File Structure

File Name

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

File encoding

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 elements

Order of the elements in a Java source file shall be

  1. License section
  2. package declaration
  3. import statements
  4. Functional comment for top level class
  5. Class declaration
  6. Constants

License section

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.

Package declaration

The package statement is not line-wrapped. The column limit does not apply to package statements.

Import 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.

Functional comment for top level class

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.

Back to top

Packages

Package Identification

Packages shall be named starting with the reverse company name for example com.company.project.module

? Why: To avoid namespace collision.

Package capitalization and words

Package names shall be all small letters and single words separated by dots.

For example:

package com.company.product.module;

Back to top

Constants

Constants specific to functionality

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";
}

Back to top

Variables

Back to top

Classes

Exactly one top level class

Each top-level class resides in a source file of its own.

Class elements ordering

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.

Back to top

Functions

Back to top

Comments

Back to top

References

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.

Back to top