Style Guide

FFSM Style Guide, draft 2

---

Table of Contents:

1. Naming Conventions
2. Indentation and Columns
3. Braces
4. Control Flow Statements
5. Spaces
6. Java (important!)
7. Miscellaneous
8. Differences from Google

Core Principle

• This guide aims to fix commonly-disputed cases and cases that eliminate simple errors, and to improve code clarity.
• Where this guide does not speak, use IntelliJ defaults.
• Where neither this guide nor IntelliJ defaults apply, use Google's coding guide.

1. Naming Conventions

• All names should be descriptive, and concise.
  • Given the choice, choose descriptive over short, but consider refactoring.
• Name classes in PascalCase
• Name top-level class members in camelCase.
• Constants should be in LOUD_SNAKE_CASE
• Local variables should be in camelCase.
• Labels, if used, should be in snake_case, and should be probably be named "outer".
  • Nothing else should be named "outer".

2. Indentation and Columns

• Indent with tabs.
• Align with spaces.
• Standard tab width is 4 spaces.
• With tab width 4:
  • Try to keep line length under 80 columns.
  • Try harder to not exceed 90 columns.
  • Never exceed a line length of 100 columns.
• Here are some approximations for other tab widths:
  • With tab width 2:
    • Try to keep line length under 75 or so columns.
    • Never exceed 90 columns. (This works up to 5 indentation levels.)
  • With tab width 8:
    • At three indentation levels, try not to exceed 100 columns.
    • At three indentation levels, never exceed 112. (+4/indent level)

3. Braces

• For class declarations, place both braces on their own line
• For method declarations, the brace follows the declaration, on the same line.
• For empty classes, {} may appear on the same line as the rest of the declaration.

public className
{
	public type methodName(args) {
		body;
	}
}

• For control flow statements, always use braces, which should share lines with the statement.

if (condition) {
	body;
} else (condition) {
	body;
}

• If using additional scoping braces, put them on their own lines.
  • Use these "anonymous scopes" sparingly, and only after careful consideration.
  • These aren't necessarily bad; but don't use them where a function would be better (i.e. the same "anonymous scope" should not be used more than once).

4. Control Flow Statements

• Always use braces with control statements.
  • The only exception is an if statement with its entire body on the same line.
  • Do not mix control flow statements with and without braces.
  • When possible, use a switch/case block without breaks.
• Never user logical operator short-circuiting as a standalone conditional.
• Indent the cases of a switch/case block.

while (condition) {
GOOD:
	     if (condition) continue;
	else if (condition) return;
GOOD:
	if (condition) {
		continue;
	} else {
		body;
	}
GOOD:
	switch (variable) {
		case 1: continue;
		case 2: break;
		case 3: return value;
	}
BAD:
	if (condition) continue;
	else {
		body;
	}
BAD:
	condition && statement;
}

• Do not use the assignment operator (=) in the condition of an if or for statement. Only use the assignment operator in the condition of a while or do-while statement after careful consideration (e.g. consider using the other statement).

• If you use the assignment operator in a loop condition, place it in an additional pair of parentheses, and leave a comment that it is intentional.

• Try to avoid having loops with many exit points.

• Use of labels:

  • Only use labels to break out of nested loops, or to break from a loop from within a switch block.
  • Name such labels "outer" or "loop", respectively. If you need more than one, ask someone else if you should refactor.
  • Before using a label, consider if there is a better option.
  • Never indent labels at all.

outer:
	while (condition) {
		while (condition) {
			body;
			break outer;
		}
	}

5. Spaces

• Put a single space on either side of a binary operator (even the assignment after for).
• Put a single space on either side of each symbol of the ternary conditional operator (?:).
• Put a single space to the right of the unary not operator (!).
• Put a single space before the opening brace of an array initializer.
• For all other space placement, use IntelliJ's default settings.

6. Java

• In a class declaration, place extends and implements each on a new line, indented twice.
• In a method declaration, put throws on a new line, indented twice.
• Always use this when possible.
• Do not use null to represent an optional value. Use Optional<T> instead.
  • See this article for reasons and how to use Optional (use Optional.flatMap()).
  • Similarly, consider returning some useful value instead of void. When in doubt, return a success value.
• Always use @override when it applies. This avoids otherwise uncaught mistakes.
• In classes, put fields first, then constructors (ordered by decreasing number of parameters), then overridden methods, then other methods.
• In overloaded methods, put arguments in the same order.
• If using multiple annotations, put each on a separate line.
• No non-static fields should be public.
• Always qualify static member access with the class name, not an instance.
• Always use getters and setters to access members of other classes.
• Remove the "created by [name]" comment inserted by IntelliJ.
• Unless using the return value of ++ or --, which you probably shouldn't (for readability reasons), always use the prefix form (++x, not x++).
• Avoid using arrays; use List<T>s instead.

7. Miscellaneous

• Never use editor-specific markings in a source file.
• Use javadoc on all classes and public members.
  • Javadoc for private members is optional, but recommended.
• When referring to sections of a building separated by stairs or elevators, use the word "floor".
  • "Level" and "story" have other meanings that could come up in this project.
• Non-Java files should be named descriptively, in PascalCase.
• Use block comments for any type of header (these may be single-line).

8. Differences from Google

This is a list of conflicts between this guide and the Google Java Style Guide.

• This guide suggests using tabs for indentation; Google suggests spaces.
• Regarding braces, this guide differs from Google only for class declarations.
  • Google goes into a bit more detail.
• This guide suggests single-tab indentation; Google suggests 2-space.
• Google goes into more details about naming, but does not conflict with this Guide.
  • Try to follow Google's guidelines for naming.
• Google strictly limits line length to 100 columns. This guide suggests 80, and also strictly limits to 100.