This document is a short guide on Java code style for this course. We’ll cover some common Java conventions as well as some other guidelines that will make it easier for all of us to read and understand each other’s code.

Capitalization

  1. Class names always start with a capital letter (e.g. String).
  2. Variable names start with a lower case letter (e.g. word), but if they contain multiple words, they use “camel case” where all words except for the first start with a capital letter (e.g. myLongVariableWithManyWords).
  3. If you are declaring a constant variable, you use all capital letters (e.g. public static final double PI = 3.14159;). If the constant variable uses multiple words, use an underscore to separate the words (e.g. MINIMUM_SIZE).

Comments

  1. Use Javadoc style comments (/** ... */) to summarize the whole class, and as a comment for each method that describes what the method does. You may also use these comments to indicate the purpose of all the fields in a class.
  2. As appropriate use regular comments (/* ... */ or //...) within methods to provide further detail on any underlying logic. I suggest writing comments by considering an audience that knows Java, but is not familiar with the details of what exactly you are trying to implement.
  3. When writing a single line comment use // instead of /* ... */.

File Organization

  1. Import statements go at the top of the file.
  2. Javadoc comments (those that start with /**) about the class/interface should include your name and go in between the import statements and the declaration of the class/interface.
  3. Instance variables and static fields go before any constructors or methods. All constructors appear before any methods.
  4. If you have a main method, it goes after all other methods.

Variable and Method Names

Use descriptive names for variables and methods. The names should give you some clue as to what data a variable stores or what the method does. It’s fine to use things like i or j for the incrementor in a loop.

Class Design

Think carefully about how you design your classes. In particular, consider the following:

  1. Should fields be public or private? Don’t make them public unless you have a good reason to do so.
  2. Instance variable vs local variable? If it refers to a persistent state it should probably be an instance variable. If it will only be used once, or only by one specific method that resets it value at the beginning, then it should probably be a local variable.
  3. Should fields be static or non-static?

Braces

Always include braces around the body of if, else, for, while, etc., even if the body is only one line long. I personally prefer opening braces placed on the following line such as:

if (line != null)
{
    System.out.println(line);
}

If you prefer, you may place the starting brace on the same line (which is recommended by the Google style guide) such as:

if (line != null) {
    System.out.println(line);
}

Indentation

Use indentation to separate out blocks of code (like you do for Python). For example, indent the bodies of methods, the bodies of loops, etc. Note: Unlike Python, this type of indentation is not required, but is quite useful for making code more readable.

White Space

  1. Do not use whitespace before a comma, semicolon, or colon.
  2. Do use whitespace after a comma, semicolon, or colon except at the end of a line.
  3. Surround binary operators (+, -, =, /, etc.) by a single space on either side.
  4. Surround comparisons (==, <, >, !=, <=, =>) by a single space on either side.
  5. Surround booleans (&&, ||) by a single space on either side. Not (!) can be placed directly in front of a variable or method without a space after it.

Commented Out Code

Do not include any code you’ve commented out when submitting an assignment (e.g. an old version of a method that didn’t work correctly), unless you are explicitly told to do so. You would never turn in an essay with paragraph simply struck through with a pen, so don’t turn in code that does that.

Acknowledgments
These guidelines were originally written by Layla Oesper and based off of the Google Java Style Guide. Later modifications were made by Eric Alexander and Titus Klinge.