Code Conventions for VIP Projects: Java.
- Introduction
- File Basics
- File Structure
- Formatting
- Naming Conventions
- Comments
- Statements
- Simple Statements
- Variable Declaration Statements
- return Statements
- Conditional Branching Statements
- Iteration Statements
- switch Statements
- try-catch Statements
- Programming Practices
- Access to Instance and Class Variables
- @Override tag
- Caught Exceptions
- Expressions before `?' in the Conditional Operator
- Bibliography
This document has the purpose to define VIP's (ICESI) coding standards for source code in the Java™ Programming Language for all of it's projects.
Code Conventions are key in the software structural quality.
Programmers are recommended to use this guidelines because:
- They improve readability, allowing programmers and engineers to understand new code easily.
- Most of the lifetime cost of a software goes to maintenance so it's important to have guidelines to help understand it and make the process easier.
- There is almost a zero chance that the original author is going to maintain the software for its whole life.z
For Suffixes, Java uses:
| File Type | Suffix |
| Java source | .java |
| Java bytecode | .class |
The source file's name consists of the case-sensitive name.
If there exist license or copyright information, it belongs in this file.
A source file consists of:
- License or copyright information, if present
- Package statement
- Import statements
- Exactly one top-level class
- Exactly one blank line separates each section that is present.
Every source files begin with a c-style comment that has the class name, version information, date, and copyright information:
After the documentation comments, the first line of a Java source file is a package statement followed by import statements.
Parts of a class or interface declaration, in the correct order:
- Class/interface documentation comment ( /**...*/)
- Class/interface statement
- Class/interface implementation comment ( /*...*/), if necessary
- Class (static) variables
- Public class variables
- Protected class variables
- No access modifier varibles
- Private variables
Braces are used with conditional (if, if-else, if else-if else), iteration (for, do and while) and try/catch/finally statements, even when the body is empty or contains a single statement.
An empty block should follow the Kernighan and Ritchie style:
- No line break before the opening brace.
- Line break after the opening brace.
- Line break before the closing brace.
- Line break after the closing brace, only if that brace terminates a statement or terminates the body of a method, constructor, or named class. There is no line break after the brace if it is followed by else or a comma.
For empty blocks braces may be closed immediately after they are opened, with no characters or line break in between, only if they aren't part of a multi-block statement.
Nomempty blocks also follow the Kernighan and Ritchie style.
The ident increases by two for every new block or block-like construct. Once the block ends the indent goes back to the previous indent level.
Each statement is followed by a line break.
Each line should have a shorter length than 80 characters.
General rules to break an expression that doesn't fit on a single line:
- Prefer higher syntactic level breaks.
- Break after a comma.
- Break before an operator.
- Align the new line with the beginning of the expression at the same level on the previous line.
A blank line always has be used in the following circumstances:
- Between sections of a source file to improve
- Between class and interface definitions
- Between methods
- Between logical sections inside a method to improve readability
- Before a block or a single line comment
- Between statements
Multiple consecutive blank lines are permitted, but not required.
A blank space always has be used in the following circumstances:
- Separating any reserved word,from an open parenthesis that follows it on that line Note that a blank space should not be used between a method name and its opening parenthesis.
- After commas in argument lists.
- Separating any reserved word, such as else or catch, from a closing curly brace (}) that precedes it on that line.
- On both sides of any binary or ternary operator. Except (.) Blank spaces should never separate unary operators such as unary minus, increment ("++"), and decrement ("--") from their operands.
- Writing the expressions in a for statement
- On both sides of the double slash (//) that begins an end-of-line comment.
- Casts should be followed by a blank space.
Every variable declaration (field or local) declares only one variable: declarations such as int a, b; are not used.
For iteration statements multiple variable declarations are acceptable in the header, and are required to be written in capital letters.
Local variables are habitually declared at the start of their containing block or block-like construct.
Any array initializer may optionally be formatted as if it were a "block-like construct."
The square brackets form a part of the type, not the variable: String[] args, not String args[].
Identifiers use only ASCII letters and digits, and, in a small number of cases noted below, underscores.
| Identifier Type | Rules for Naming |
| Packages | Package names are all lowercase ASCII letters, with consecutive words simply concatenated together (no underscores). |
| Classes | Classes names should be nouns, in mixed case with the first letter of each internal word capitalized. |
| Interfaces | Interface names may be nouns or noun phrases, but may sometimes be adjectives or adjective phrases instead. They should be capitalized like class names. |
| Methods | Method names are typically verbs or verb phrases, in mixed case with the first letter lowercase, with the first letter of each internal word capitalized. |
| Constants | Constant names should be all uppercase with words separated by underscores ("_"). |
| Variables | Variables names should be all lowercase, with the exception of variables in the header of iteration methods. They should not start with underscore _ or dollar sign $ characters, and even though both are allowed we do not encourage them. |
| Parameters | Parameter names should be all lowercase. One-character parameter names in public methods should be avoided. |
Block comments are used to provide descriptions of files, methods, data structures and algorithms. Block comments may be used at the beginning of each file and before each method.
A block comment should be preceded by a blank line to set it apart from the rest of the code.
Short comments can appear on a single line indented to the level of the code that follows. If a comment can't be written in a single line, it should follow the block comment format (see previous definition).
A single-line comment should be preceded by a blank line.
Very short comments can appear on the same line as the code they describe, but should be shifted far enough to separate them from the statements.
The // comment delimiter can comment out a complete line or only a partial line. It shouldn't be used on consecutive multiple lines for text comments; however, it can be used in consecutive multiple lines for commenting out sections of code.
See section: 3.ii.a Documentation Comments
Each line should contain at most one statement.
See section: 4.v. Specific Constructs
A return statement with a value should not use parentheses unless they make the return value more obvious in some way.
The if statements should have the following form:
The if-else statements should have the following form:
The if else-if else statements should have the following form:
A for statement should have the following form:
An empty for statement should have the following form:
A while statement should have the following form:
An empty while statement should have the following form:
A switch statement should have the following form:
Every switch statement should include a default case. The break in the default case is redundant, but it prevents a fall-through error if later another case is added.
A try-catch statement should have the following form:
A try-catch statement may also be followed by finally, and it should have the following form:
