Coding Conventions

Coding Conventions

We typically follow these conventions when coding in most cases. We may request changes to your pull request based on the below. Please note that this doesn't always mean your code is "wrong", but it may be inconsistent relative to the conventions we've adopted. Where possible, we'll explain why we used certain conventions.

General Conventions

Convention	Explanation
Use Explicit Types (not var)	We always prefer explicit types vs var. We feel the code is easier to read when the type is right there.
Use Interface Types	Unless there's good reason to do so, avoid using raw classes. Use interfaces instead. This makes the code easily separable by the interface separation principle. So if you have a class A and a class B which uses A, rather than reference A directly from B, the recommendation is to create an interface IA, exposing only the public methods of A and then make B depend on IA.
Variable Naming	As far as possible, variables should be named so that the meaning of the variable can be inferred from the variable name. You can always start coding with variables like i and j and then when it's time to commit your code, you can use your IDE to rename the variables to something more descriptive e.g. rowIndex and columnIndex. The variable names should tell a story. They should be descriptive enough that you rarely ever need to use comments.
Use Local Variables to store Interim Calculations	This convention could also have been called "avoid using lengthy expressions". It's best demonstrated with an example. Suppose you have this code: PrintTotalVolume( + length2*breadth2*height2). Instead, we would favour four lines of code: double volume1 = length1*breadth1*height1; then double volume2 = length2*breadth2*height2, then double totalVolume = volume1 + volume2 and finally PrintTotalVolume(totalVolume).
Clean Code, not Cluttered Comments	If you are following other best practices such as good variable naming and using local variables to store interim calculations, then your code should tell a story as it is written. If you find yourself beginning to write a comment to explain a bit of complex code, the first rule of thumb is: can the code itself be broken down, simplified, and renamed in such a way that the comment is unnecessary? If so, you are always advised to make the code change rather than add comment clutter on top of complex code. There are exceptions to this, but they are rare. For example you might need to do some weird trick to avoid a bug in an API over which you have no control. In that case, a comment is absolutely justified.

Testing Conventions

Convention	Explanation
Name methods using given, when, then format	This format makes it easier to understand the purpose of the test method without reading the code. For example, do not use method names such as: methodATest. Instead, name them something like: Given_StartingCondition_When_SomethingHappens_Then_TheExpectedResultIsX
Use the AAA pattern for tests (#30)	The idea is to use comments to split the test method into 3 sections: "Arrange", "Act", and "Assert". This convention makes it easier to get a high level view of what the test is doing and forces the code in the test to follow a logical sequence. Note: the arrange, act, assert sections correspond to the given, when, then conditions of our test, respectively. The arrange section produces the given condition. Assertions may be carried out in this section but any such assertions should start with the uppercase label "GIVEN: ". This ensures that it's obvious when a test fails due to poor arrangement code rather than the act code itself failing. The act section in turn should call upon the unit of functionality being tested. The assert section then contains assertions about the post-condition after the act e.g. checking that some object's internal state has been modified to satisfy some condition, or checking that an object returned by a method satisfies some condition. Assertion methods are optional, but often encouraged, if they make the failure clearer: think about someone running your test many years in the future. Will they understand a failure if it occurs?

---

...More conventions will follow. Please be patient with us as we convert our coding experience to text...