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.

Source File Structure

All source files must begin with a block comment that contains a copyright notice and the text of the license, such as the following:

/*
 * Copyright (c) 2024 - The MegaMek Team. All Rights Reserved.
 *
 * This file is part of MegaMek.
 *
 * MegaMek 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 3 of the License, or
 * (at your option) any later version.
 *
 * MegaMek 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.
 *
 * You should have received a copy of the GNU General Public License
 * along with MegaMek. If not, see <http://www.gnu.org/licenses/>.
 */

Wildcard imports are permitted.

Formatting

Braces

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, separated from the closing round bracket by a space. 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  

Indentation

All block indentations are four spaces. Never tabs. Each case block in a switch statement should be indented one level.

Whitespace

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

Parentheses

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.

Identifiers

Classes

Names of classes, interfaces, and enums should always be UpperCamelCase, with the first letter of every word capitalized and all other letters lowercase.

Variables and Methods

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. The this. keyword as a prefix should only be used where necessary (e.g. in this.name = name).

Constants

Constants should be in all caps, with an underscore used to separate words. This includes fields that are declared static final and enum values.

Comments and Documentation

JavaDoc

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.

Annotations

When overriding an inherited method, the @Override annotation should always be used.