-
Notifications
You must be signed in to change notification settings - Fork 291
MegaMek Coding Style Guide
Consistency is an important factor in code readability. Any code submitted to MegaMek, MegaMekLab, or MekHQ should follow the coding style outlined here. Anything not covered in can probably be left up to the coder's preference, but if there is any doubt the Google Java Style Guide is a good source.
Note that MegaMek has been around for decades and has had many contributors over the years. Not all of the current code base adheres to these guidelines. These are the guidelines for new code, and old code is being brought into compliance gradually.
All source files must begin with a block comment that contains a copyright notice and the text of the license, such as the following:
/*
* MegaMek - Copyright (C) 2020 - The MegaMek Team
*
* This program is free software; you can redistribute it and/or modify it under
* the terms of the GNU General Public License as published by the Free Software
* Foundation; either version 2 of the License, or (at your option) any later
* version.
*
* This program is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
* FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
* details.
*/
Wildcard imports are permitted.
Braces follow the Kernigan and Ritchie style. The opening brace comes at the end of the line with the class declaration, method declaration, or control statement, and the end brace is on a line by itself unless followed by a reserved word that is part of the block or connects a multi-block statement (else, catch, finally, while).
Examples:
class Foo {
// class definition
}
if (booleanExpr) {
// do a thing
} else {
// do a different thing
}
Braces are never omitted following if, else, for, while, or do, even for a single statement or an empty block:
if (booleanExpr) doSomething(); // wrong
if (booleanExpr) { //right
doSomething();
}
Empty blocks may appear on the same line if not part of a multi-block (if/else or try/catch) statement:
public void maybeDoTheThing() {} // ok
try {
defuseBomb();
} catch (WrongWireException ex) {} // not ok
All block indentations are four spaces. Never tabs. Each case block in a switch statement should be indented one level.
A space should be used within a line in the following circumstances:
- Between a reserved word and a parenthesis or a brace.
- Between a parenthesis and a brace.
- On both sides of a binary or ternary operator, with the exception of a method reference (::) or the dot separator (.).
- After a comma
When building boolean expressions using multiple operators, the component expressions should be grouped explicitly:
if ((a == b) && (c == d))
rather than
if (a == b && c == d)
If the number of extra parentheses makes the expression hard to read, it needs to be refactored anyway.
Names of classes, interfaces, and enums should always be UpperCamelCase, with the first letter of every word capitalized and all other letters lowercase.
The names of methods and variables (including fields, local variables, and named parameters) should be lowerCamelCase, starting with a lower case letter and having the first letter of each additional word capitalized.
Constants should be in all caps, with an underscore used to separate words. This includes fields that are declared static final and enum values.
All public or protected methods and classes should be documented with a JavaDoc comment, but is good practice to do so for package and private methods as well. Exceptions can be made when in trivial cases where it is obvious what the method does, such as basic setters and getters, but it is better to err on the side of overdocumenting. It is not necessary to repeat the documentation when overriding a method that is documented in the parent class unless the method is overridden to do something that is not covered in the documentation of the parent class.
When overriding an inherited method, the @Override annotation should always be used.