Code Standards Draft - SWG-Source/swg-main GitHub Wiki

• Objects and Classes should be PascalCase like Location or NetworkId or RegionQuadTree
• Methods, Functions, and Variables should be camelCase like checkStatusOfThing() or doThis() or playerCurrentState and should be written as verbs or prefixed with a verb followed by the name of the target, like getThing() or setValue().
• Constants and Enumerations should be in SNAKE_CASE like SOME_SPECIFIC_VALUE or FACTION_HASH_IMPERIAL
• Boolean types should ask a yes/no question in their name, like isEligible() or shouldDoThing() or canDoThing. is is the preferred usage.
• Always ensure your naming makes clear what things are and what they do.
• Pay attention to semantics and exercise caution when using terms that have multiple meanings as the definitions of certain words in the context of the SWG source may mean something different than its common definition.

• Everything that can go in branches should be in braces. Even single-line if statements.

if(isEligible())
     setTravelAllowed(); // don't do this

• Single blocks should not be reduced to one line

static boolean isEligible(obj_id player) { return true; } // don't do this

• In Class and Object Definitions and Abstractions/Interfaces, braces should be on new lines, like:

CollisionBuilder::CollisionBuilder(MayaHierarchy::Node const * pNode)
{
     if(isValid(m_pNode)
     {
          m_pNode = pNode;
     }
}

• In Inline Blocks and non-class structure, braces should be on the same line in opening, but a separate line for closing, (mainly in scripting and in-class private functions) like:

for (thing t : thingArray) {
     doThing(t);
}

• Use 5 point tabs, not spaces everywhere
• Always tab-in when inside a braced block of code.

• Foremost, prioritize writing self-documenting code, like:

int i = x + (c * e); // don't do this
int totalScore = basePoints + (rangeMultiplier * rangeEligiblePoints); // do this

• Especially in long blocks of code, annotate blocks by "way of thinking out load" not just describing what something does

// iterate < bad!
for (int i = 0; i < squelchList.length; i++) {
     messageTo(squelchList[i], "requestUpdate", null, 0f);
}
// Begin iterating through the Squelched Players list to send notification requesting a presence update so we have the latest list by the time we get to the call b <<< good!
for (int i = 0; i < squelchList.length; i++) {
     messageTo(squelchList[i], "requestUpdate", null, 0f);
}

• Always add JavaDoc-Style comments above methods describing what they do, how to use them, their purpose, and any notes (exception: unless it is so glaringly obvious because of the naming and it is a short/simple method). Like:

 /**
* @param type LEADERBOARD_TYPE_FISHING or LEADERBOARD_TYPE_GCW
* @param faction FACTION_HASH_IMPERIAL or FACTION_HASH_REBEL
* @param period LEADERBOARD_PERIOD_CURRENT, LEADERBOARD_PERIOD_PREVIOUS, or LEADERBOARD_PERIOD_2WEEKSAGO
* @return float[] of scores of ranked cities for the current period given the type and faction
* 
* Scores are in rank order from 1st to 10th to match the value pair of the getRankedCitiesForPeriod() method
*/
public static float[] getRankedCityScoresForPeriod(int type, int faction, int period) {

• In Java, variables whose values will not change further in a block should be declared final. In C++, const should be used as appropriate with normal C++ standards.

• We welcome and encourage newer concepts (e.g. ranged-based for loops, lambdas, etc.) when they are appropriate and especially when more programmatically efficient.

• The use of Java's String.format() or similar is preferred over concatenation.

String message = "We found "+numPlayers+" players in range of you."; // don't do this
String message = String.format("We found %i players in range of you.", numPlayers); // do this

Use intermediate variables to simplify complicated expressions. Like:

// this
if(canTravelToTansariiStation(player) && getPlayerLevel(player) < 10 && !getCurrentScene().equalsIgnoreCase("tutorial")) {}
// would be better as
final boolean playerIsQualified = getPlayerLevel(player) < 10 && !getCurrentScene().equalsIgnoreCase("tutorial");
if(canTravelToTansariiStation(player) && isPlayerQualified) {}

When unavoidable and committing code with to-do items that remain, please use to-do comment blocks at the TOP of the file only as //todo <thing>. If you intend to complete those items yourself, you can prepend with the responsible person, like //todo (Aconite) finish implementation of canCrash().