This document introduces the Java code style conventions used in the SwEng assignments. They were inspired by the standard Java code guidelines
, together with the Google Android project code conventions
These conventions are enforced by the Android Studio configuration provided with your project skeleton.
The rest of this document outlines the most important style rules present in the configuration. Please note that this has an informative role only, and may not be fully accurate. The exact rules used for grading your work are ultimately determined by the Android Studio configuration provided with your project skeleton.
- Opening curly brace should appear on the same line as the previous statement. The closing curly brace should appear on a separate line.
- Use braces even for single-statement blocks in if/else or for/while/do constructs.
- Each variable declaration should happen on a separate line of code.
- Constant names should be capitalized, and individual words in the name should be separated by underscores (_).
- Class names should have the first letter of each word capitalized.
- Method names should have the first letter of each word capitalized, except for the first word, which should be lower-case.
- Variable names should be formatted the same as method names.
Whitespace and Code Comments (Javadoc)
- Proper indentation. Each block of code should be indented one more level relative to the parent enclosing block. Each indentation level should be 4 spaces. Do not use the TAB character.
- You should comment your code as much as possible. In particular, all public classes and public fields/methods need to have an associated Javadoc comment.
- Note: this is not enforced by the Android Studio configuration
Code Size Limitations
- Each line should be at most 120 characters wide. You can configure Android Studio to show this margin by going to File/Settings/Default Settings, then accessing the Code Style/General. There, you should make sure to set 120 as the Right margin value.
- Each Java file should have at most 2000 lines. If this file becomes larger, you should consider breaking the functionality in separate Java classes. You can configure Android Studio to show line numbers by going to File/Settings, then accessing the Editor/General/Appearance pane. There, you should check the Show line numbers option.
- Each method should be at most 150 lines long. If the method becomes larger, you should consider breaking the method functionality into multiple methods.
- Each method should take at most 7 parameters. If you find yourself needing more parameters, you should consider, for instance, grouping the parameters into a larger object, pre-configuring the object before invoking the method, etc.
- Avoid wildcard imports (e.g., import java.util.*;). Import only the classes that are used by the current compilation unit. In particular, Android Studio can manage the imports automatically for you..
- Avoid illegal imports, such as the platform specific ones (sun.*). You may accidentally end up importing such classes if Android Studio finds a class with the same name in the sun package, and you don't select the correct one to import.
- Group imports by package. The groups should be separated by an empty line. Android Studio does this automatically for you, if you let it add the imports automatically.
Good Code Practices
- The object equals() and hashCode() methods should be implemented together. Never implement one without the other, or your code may break.
- When comparing strings for equality, you should use the equals() method instead of the == operator.
- Catch exceptions as specifically as possible. For instance, when a method may throw both IOException and FileNotFoundException, you should catch each of these in a separate catch block. Avoid catching general Exception or RuntimeException exceptions.