Created Code Standards - Draft (markdown)

Code-Standards---Draft.md

@@ -0,0 +1,94 @@
+## Naming Nomenclature
+* 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.
+
+## Braces
+* **Everything that can go in branches *should* be in braces**. *Even single-line if statements*.
+```cpp
+if(isEligible())
+     setTravelAllowed(); // don't do this
+```
+* Single blocks should not be reduced to one line
+```java
+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:
+```cpp
+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:
+```java
+for (thing t : thingArray) {
+     doThing(t);
+}
+```
+
+## Tabs and Indenting
+* Use 5 point tabs, not spaces everywhere
+* Always tab-in when inside a braced block of code.
+
+## Comments
+* Foremost, prioritize writing self-documenting code, like:
+```java
+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
+```java
+// 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:
+```java
+ /**
+* @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) {
+```
+
+## Liberal Use of Final/Const
+* 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.
+
+## New Code 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.
+
+## String Formatting
+* The use of Java's `String.format()` or similar is preferred over concatenation.
+```java
+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
+```
+## Complicated Expressions
+Use intermediate variables to simplify complicated expressions. Like:
+```java
+// 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) {}
+```
+
+## To-Do List Items
+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()`.
+