Coding Guidelines

Coordinator
May 17, 2013 at 7:38 AM
Edited May 17, 2013 at 7:45 AM
C#
Naming

Name members, classes and variables according to their purpose or content. For example: UserViewModel instead of PrepareUsers.

Do not use abbreviations for identifiers.

Name source files after their contained class. There is only one class per file.

Name projects and folders according to their contained namespace.

The name of a class in general consists of speaking nouns that give a good hint on the purpose of the class.

The name of a method usually starts with a verb. Sometimes a noun or adjective follows. Example: Add, RemoveAll, GetLength.

Custom exception classes have the suffix Exception.

Custom attribute classes have the suffix Attribute.

Casing

Identifier Capitalization Style Prefix Examples
Class Pascal casing LiveViewer
Enum type Pascal casing OutputFormat
Enum values Pascal casing Plain, WithPictures
Event Pascal casing ButtonPress
Field (private) camel casing _ _value, _backColor
Constant Pascal casing SomeConstant
Interface Pascal casing I IValueConverter
Method Pascal casing Clear, RemoveAll
Parameter (in method declarations) camel casing value, backColor
Property Pascal casing Value, BackColor
Type parameter in generics Pascal casing ObservableCollection<Type>
Variable camel casing value, backColor
XAML element names camel casing <Button x:Name=”loadItems” …/>

Formatting

Place curly brackets always in a new row.
Do not omit curly brackets.
public void Foo(bool mork)
{
   if (mork) //wrong
      CallMork();
   else //correct
   {
       CallAlf();
   }
}
For indentation configure your IDE to put 4 spaces instead of a tabulator. This is the standard configuration in VS.

Architecture

Apply the common [GoF] design patterns where appropriate (Factory, Flyweight, Wrapper, Facade, Composite and so on). It helps other programmers to understand your code. Moreover, there are standard pattern for most purposes. Do not invent the wheel again. If the name of a class does not identify the pattern you may mention the pattern in the documentation.

Methods and functions follow the principle of single purpose. A method name like AddNumbersAndReadWebservice obviously does more than one thing. Classes as well have to serve a certain purpose, it shall not be a swiss-army-knife.

Keep the number of exit points for a method small.
public ResultClass Foo(InputClass bar)
{
   ...validation here... throw exceptions
   ...early return here, e.g.
   if (bar.IsTrivial)
   {
      return ResultClass.TrivialResult;
   }
   ResultClass result;
   ...determine result plus some processing here, no exit in between...
   return result;
}
Implement the IDisposable interface only when necessary. If so (unmanaged resource, checking for out of scope), then implement it correctly, surround its scope with the keyword using. Avoid it in context of composites. If the child of a composite implements IDisposable the composite has to as well.

Refactoring is an ongoing process. If the code you currently work on contains code duplicates, is inaccurate, not testable or strikes your architecture, then refactor it.

Never hide members of a base class. Use the keyword override to override a base class member. Never use new for that purpose and never omit the keyword.

Aggregation over Inheritance. This supports re-usability of code. Inherit only if the relationship between two classes truly is “is-a”.

When aggregating, implement against interfaces and add the child objects by dependency injection/Inversion of control – some controller/manager class adds the aggregated children, for example from a configuration. You will be thankful for it as you write unit tests or want to reuse or exchange modules.

Comments

Write an XML code documentation for classes and all members that belong to a public API. XML documentation is created by typing the triple dash /// above a definition.

Write down the purpose and usage of a class or method, when there is something to mention. Do not write down other interesting stuff, like how you came there, all the alternatives you thought about or who has implemented this. Those are subjects to change, you will definitely not maintain comments to keep them up to date.

When the functioning of method is not obvious, add in code comments. Do not surround with dash and star //, but double dash //. If you feel forced to write comments inside your code, it is often a sign that you should refactor your code instead. Comments are code smell.

Automated tests are part of the documentation They describe what a method does. Use comments to describe their purpose.

Miscellaneous

Use the keyword var in context of anonymous classes or for result sets of LINQ queries, which may construct very complex generic types. Be reluctant in using var instead of full qualifiers. When code blocks and especially methods clearly describe what they actually, then as developer you don’t need to see the actual type of a variable. When you live clean code, var is no hurdle.

If you feel you have to break a rule, then ask your team members for alternatives or consensus. Comment your intention, when breaking rule inside the code.

Functionality over Performance. Write code that does the correct thing in first place. Performance tweaking is a time stealing process, which often is unnecessary micro-tuning.

We program according to test-driven-development. Test first is our directive.

Write tests for the contract of a class (public, internal) as it describes the expected behaviour. There is no requirement to create unit test for private and protected members.

Integrate frequently. Check-in small changes that compile, do not break tests and describe a single technical aspect. Do not mix implementation and refactoring on check-ins.
Coordinator
May 17, 2013 at 7:46 AM
XAML
Placeholder
Coordinator
May 17, 2013 at 7:49 AM
Java
Placeholder