Introduction

1.1 What is this?

This document attempts to provide guidelines (or coding standards if you like) for all versions of C# up to and including 7.3 that are both valuable and pragmatic. Notice that not all guidelines have a clear rationale. Some of them are simply choices. In the end, it doesn’t matter what choice you make, as long as you make one and apply it consistently. This document was based on an open source version found in GitHub. It has been adapted to reflect HTA’s principles and guidelines.

1.2 Why would you use this document?

Although some might see coding guidelines as undesired overhead or something that limits creativity, this approach has already proven its value for many years. This is because not every developer:

  • is aware that code is generally read 10 times more than it is changed;
  • is aware of the potential pitfalls of certain constructs in C#;
  • is up to speed on certain conventions when using the .NET Framework such as IDisposable, async/await, or the deferred execution nature of LINQ;
  • is aware of the impact of using (or neglecting to use) particular solutions on aspects like security, performance, multi-language support, etc;
  • realizes that not every developer is as capable, skilled or experienced to understand elegant, but potentially very abstract solutions;

1.3 Basic principles

These include:

  • The Principle of Least Surprise (or Astonishment): you should choose a solution that everyone can understand, and that keeps them on the right track.
  • Keep It Simple Stupid (a.k.a. KISS): the simplest solution is more than sufficient.
  • You Ain’t Gonna Need It (a.k.a. YAGNI): create a solution for the problem at hand, not for the ones you think may happen later on. Can you predict the future?
  • Don’t Repeat Yourself (a.k.a. DRY): avoid duplication within a component, a source control repository or a bounded context, without forgetting the Rule of Three heuristic.
  • The four principles of object-oriented programming: encapsulation, abstraction, inheritance and polymorphism.
  • In general, generated code should not need to comply with coding guidelines. However, if it is possible to modify the templates used for generation, try to make them generate code that complies as much as possible.

Regardless of the elegance of someone’s solution, if it’s too complex for the ordinary developer, exposes unusual behavior, or tries to solve many possible future issues, it is very likely the wrong solution and needs redesign. The worst response a developer can give you to these principles is: “But it works?”.

1.4 How do you get started?

  • Ask all developers to carefully read this document at least once. This will give them a sense of the kind of guidelines the document contains.
  • Include the most critical coding guidelines on your Project Checklist and verify the remainder as part of your Peer Review.
  • ReSharper has an intelligent code inspection engine that, with some configuration, already supports many aspects of the Coding Guidelines. It automatically highlights any code that does not match the rules for naming members (e.g. Pascal or Camel casing), detects dead code, and many other things. One click of the mouse button (or the corresponding keyboard shortcut) is usually enough to fix it.
  • ReSharper also has a File Structure window that displays an overview of the members of your class or interface, and allows you to easily rearrange them using a simple drag-and-drop action.

1.5 Is this a coding standard?

The document does not state that projects must comply with these guidelines, neither does it say which guidelines are more important than others. However, we encourage projects to decide themselves which guidelines are important, what deviations a project will use, who is the consultant in case doubts arise, and what kind of layout must be used for source code. Obviously, you should make these decisions before starting the real coding work.

To help you in this decision, I’ve assigned a level of importance to each guideline:

Guidelines that you should never skip and should be applicable to all situations

Strongly recommended guidelines

May not be applicable in all situations

1.6 Feedback and disclaimer

This document has been compiled using many contributions from community members, blog posts, on-line discussions and many years of developing in C#. If you have questions, comments or suggestions, check out our Wiki (authorized access) page. In our ‘Lightning Talk’ slides section, you can find more information on how you can contribute to making these guidelines even better!

This document is published under a Creative Commons license, specifically the Creative Commons Attribution-ShareAlike 4.0 license.