Coding Conventions

These are the official coding guidelines used by Nuclex Development Labs.
The goal of this document is not to define a rigid, bureaucratic set of rules that are
tedious to comply with, but to complement the programmer in creating readable
and understandable code. All rules are intuitive and based on solid reasoning.

In general, we try not to stray from the mainstream in any major point, so as not to
alienate us from the code of other programmers or from the classes offered by
the .NET base class library.

The Motto:short – simple – obvious

1. File Structure

Establishing a common order of elements in each source file greatly helps programmers to
navigate unknown code. In this context, we believe that someone looking at the code should
first see the actual methods he can call from the outside and only then get to see the class’
bowels (namely, private methods and fields).

1.1 Order class elements by visibility

When you look at a class someone else has written, the first thing you want to see are
its constructor and the public methods it exposes, not the implementation details.
Thus, we order elements by their visibility, firs comes public, then
protected, then internal and finally private
members.

Place any definitions (such as nested classes, delegates and events) at the top of a class
to give the reader an easy overview of the nested types and connection points belonging to
the class. Next comes the constructor(s), the finalizer and the Dispose() method,
if any. Then follow up with normal methods and properties. Fields are at the very bottom of
the class because you can easily jump there (Strg+End) and because they’re definitely not
the first thing another programmer wants to know about your class.

1.2 Order class elements logically

Apart from the ordering by visibility, you should organize your files logically.
For example, try to keep methods called by other methods directly below those,
place different overloads of the same method next to each other and move
methods not depending on each other close together if they are related.

1.3 Keep source files below 500 lines

No source file is allowed to become longer than 500 lines. In fact, you should try to stay way
below that number. If you feel the need to write classes taking more than 500 lines, either
the design of your class is too complex, your class tries to take on multiple roles or you
haven’t properly identified reusable code sections and broken them down into small, understandable
methods and helper classes.

There is always the option to factor out concepts and strategies into separate, reusable classes.
This applies even more to UI classes that become too large by the mere amount of controls they
need to manage, which not only is problematic for the developers, but also repels the end-user
with overly complex dialogs.

2. Naming and Casing

Using concise, descriptive names is the most important thing about writing code. Try, figuratively,
hitting the nail on the head whenever you name something. Always try to find a simple term
that gives the reader the right idea about what a variable or method does. If you really can’t find
a fitting term (or combination thereof), just standardize the closest matching term for this
specific use throughout the project and document that!

2.1 Do not use abbreviations

Even well-known abbreviations make identifiers harder to read and in combination produce
ugly chunks of letters. Your code becomes more esthetical and it helps to keep your variable
names simple if you force yourself to avoid abbreviations at all costs. There are very few
exceptions (like, Xml) and you certainly shouldn’t add more to those 🙂

2.2 Write all your names in proper English

Any variable, method or class name you choose should follow the conventions of the
English language. Do not twist words around (eg. not FileOpen/FileClose
but OpenFile/CloseFile instead) and use the correct plural forms
(eg. not Childs, but Children instead). Do not use prefixes for your
identifiers (a prime example of prefixes would be Hungarian notation). The only exception
to this rule is that interface names are prefixed with an I, for the sake of
keeping in compliance with .NET Framework conventions and nothing else.

2.3 Use NormalCase for public and camelCase for private elements

In order to not produce schizophrenic code when interacting with the .NET Framework, all public
elements follow the same naming rules that the .NET Framework uses. Thus, anything that can be
seen from the outside of a class, including internal and protected members, is written in
NormalCase. Private things such as private methods and local variables are written in
camelCase. Place uppercase letters only after complete English words, not after each
syllable (eg. not DisConnect but simply Disconnect; not
ReMove but Remove).

3. Braces

We handle all the different kinds of braces with just one rule (C# actually has 4 kinds of
braces: curly braces, brackets, rounded braces and wedges). That means if the argument list
of a method becomes too long, break it the same way as you break the code inside a multi-line
if statement. One rule for everything.

3.1 Put opening braces at the end of the line

We like our opening braces at the end of declarations and control flow keywords. The
indentation already shows very well where a block begins and where it ends. There have
even been successful languages (Python being the most prominent example) that rely
solely on indentation to determine the length of blocks. Free standing curly braces would
act as semi-empty lines whereas we believe that empty lines should instead be at the
programmer’s disposal to separate logical sections of code.

3.2 Always use curly braces for cases in a switch statement

This is mainly for consistency reasons, since historically, the switch
and case statements don’t blend in with the rest of the language
very well. Using curly braces for each case in a switch
statement makes the indentation more logical and prevents variables declared in one
case from becoming visible in the scope of other cases.

4. Indentation and Line Breaks

Indentation in general is a matter of personal preference and regularly subject to
discussion. Using a consistent scheme throughout an entire project goes a long way in
helping developers quickly grasp the workings of the code without being irritated by
small discrepancies from the style their brain is currently trained to read.

4.1 Indent any nested block by 2 spaces

Indentation is done with spaces, not tabs. This keeps code looking identical in
web browsers and editors with different tab widths. While of course the nesting level
should not go too deep, 2 spaces provide good visual cue without scattering the code
all over the horizontal width of an editor for developers using larger fonts or
a lower screen resolution.

4.2 Limit your lines to 100 columns at most

This is not just a suggestion, it’s an actual rule. Creating long
lines will prevent the developer from seeing what’s going on and
require him to scroll the text window or enable line wrapping, both
of which are awkward for anyone trying to get a quick grasp of the
code. It will also make it harder to post code snippets on the web
or to print them. So do not cross the 100 column boundary, ever.

4.3 Try to break long lines at the brace level

When you decide to break a long line, try to do so after an
opening brace (or a comma sign if no brace is available). As outlined
in section 3, the opening brace is left at the end of the line,
while everything that was inbetween the braces goes into the next
line(s), indented by 2 spaces. Example:

5. Special Regulations

Some additional regulations not fitting into any of the topics laid out above:

5.1 Dot not wrap fields in pointless properties

Do not write useless properties around fields if there’s not reason to do so!
If you write a Vector or Matrix class for your math
library, just expose the X, Y, M11 etc.
fields. Use properties where they make sense: when you need to check assigned
values of validity or need to perform a calculation to return a value
(such as when a rectangle’s Width property calculates
Math.Abs(X2 - X1) to determine the width).

5.2 Keep your code together

Try not to create too many assemblies (eg. don’t create a separate assembly
for each namespace). It might feel nice and clean to have lots of assemblies
with different logical responsibilities, but the inter-assembly dependencies quickly
become a real pain to manage and it leaves a negative impression when someone
has to identify all the different assemblies required to use a given class by
working his way through the dependency tree one step at a time. This is very much
a matter of experience and taste, so please consult other developers when you’re
unsure on whether you should create a new assembly or extend the responsibilities
of an existing assembly.

5.3 Use regions very sparingly

Never use regions to group things like your constructors,
public methods or fields. This only serves as an annoyance to other developers,
obstructing their view of the code and causing them additional work unfolding
the regions.

Good uses of regions are few and far between. If you have a nested helper class
(remember nested classes go at the top), that should go into a region so other
developers don’t have to scroll over it in order to see the constructor and public
methods. Simple noise like a ton of secondary interface methods for implementing
tedious interfaces like IList<T> or
IDictionary<K, T> can also be hidden inside a region.