Encodo C# Handbook
This article was originally published on the Encodo Blogs. Browse on over to see more!
The first publicly available version of the Encodo C# Handbook is ready for download! It covers many aspects of programming with C#, from naming, structural and formatting conventions to best practices for using existing and developing new code.
Here’s the backstory on how and why we decided to write a formal coding handbook.
Here at Encodo, we started working with C# less than a year ago. We decided early on that we would be building a framework on which we would base our projects, both internal and external. That framework now exists and forms the core of several client projects: it’s called “Quino” and you can find out more at the Quino home page. Since we were library-oriented from the get-go, we were very aware of our coding style and were interested to know how other projects and developers organized and formatted their code and how they worked with the .NET framework.
Naturally, there was a lot of documentation to be found in Microsoft’s MSDN, but it was scattered over dozens of pages and wasn’t very useful as a consolidated reference. It also made recommendations that Microsoft themselves ignored in their own code. Searching with Mr. Google brought up numerous references to a manual from iDesign, which is quite good. Philips also has a pretty extensive manual.
We started with those as well as a bushel of ad-hoc rules we’d developed over the years and an “Encodo Style” slowly evolved. Where we diverged from other companies is that we decided to write it all down. Every last niggling bit of it. The handbook was in a very ad-hoc format when we hired Marc and realized that we’d need to get him up to speed on how we work at Encodo. After an initial formatting effort, there followed a few months of slow accretion of new rules as well as a refinement of existing ones.
Where our guide differs from the others is in the organization; there are clear sections for structure, formatting, naming, language elements and best practices instead of just a hodge-podge of rules. We’ve also done our best to weed out conflicting or repeated rules. The current handbook (version 1.4) also includes rules for those of you, like us, who’ve moved on to VS2008 and the wonderful world of .NET 3.5.
Though there will certainly be updates as we learn more, we hope you like what we’ve got so far and welcome any and all feedback!
For your quick persusal, here’s the current table of contents:
Table of Contents 1 General 1.1 Goals 1.2 Scope 1.3 Fixing Problems in the Handbook 1.4 Fixing Problems in Code 1.5 Working with an IDE 2 Design Guide 2.1 Abstractions 2.2 Inheritance vs. Helpers 2.3 Interfaces vs. Abstract Classes 2.4 Modifying interfaces 2.5 Delegates vs. Interfaces 2.6 Methods vs. Properties 2.7 Virtual Methods 2.8 Choosing Types 2.9 Design-by-Contract 2.10 Controlling API Size 3 Structure 3.1 File Contents 3.2 Assemblies 3.3 Namespaces 3.3.1 Usage 3.3.2 Naming 3.3.3 Standard Prefixes 3.3.4 Standard Suffixes 3.3.5 Encodo Namespaces 3.3.6 Grouping and ordering 4 Formatting 4.1 Indenting and Spacing 4.1.1 Case Statements 4.2 Brackets (Braces) 4.2.1 Properties 4.2.2 Methods 4.2.3 Enumerations 4.2.4 Return Statements 4.3 Parentheses 4.4 Empty Lines 4.5 Line Breaking 4.5.1 Method Calls 4.5.2 Method Definitions 4.5.3 Multi-Line Text 4.5.4 Chained Method Calls 4.5.5 Anonymous Delegates 4.5.6 Lambda Expressions 4.5.7 Ternary and Coalescing Operators 5 Naming 5.1 Basic Composition 5.1.1 Valid Characters 5.1.2 General Rules 5.1.3 Collision and Matching 5.2 Capitalization 5.3 The Art of Choosing a Name 5.3.1 General 5.3.2 Namespaces 5.3.3 Interfaces 5.3.4 Classes 5.3.5 Properties 5.3.6 Methods 5.3.7 Parameters 5.3.8 Local Variables 5.3.9 Events 5.3.10 Enumerations 5.3.11 Generic Parameters 5.3.12 Lambda Expressions 5.4 Common Names 5.4.1 Local Variables and Parameters 5.4.2 User Interface Components 5.4.3 ASP Pages 6 Language Elements 6.1 Declaration Order 6.2 Visibility 6.3 Constants 6.3.1 readonly vs. const 6.3.2 Strings and Resources 6.4 Properties 6.4.1 Indexers 6.5 Methods 6.5.1 Virtual 6.5.2 Overloads 6.5.3 Parameters 6.5.4 Constructors 6.6 Classes 6.6.1 Abstract Classes 6.6.2 Static Classes 6.6.3 Sealed Classes & Methods 6.7 Interfaces 6.8 Structs 6.9 Enumerations 6.9.1 Bit-sets 6.10 Nested Types 6.11 Local Variables 6.12 Event Handlers 6.13 Operators 6.14 Loops & Conditions 6.14.1 Loops 6.14.2 If Statements 6.14.3 Switch Statements 6.14.4 Ternary and Coalescing Operators 6.15 Comments 6.15.1 Formatting & Placement 6.15.2 Styles 6.15.3 Content 6.16 Grouping with #region Tags 6.17 Compiler Variables 6.17.1 The [Conditional] Attribute 6.17.2 #if/#else/#endif 7 Patterns & Best Practices 7.1 Safe Programming 7.2 Side Effects 7.3 Null Handling 7.4 Casting 7.5 Conversions 7.6 Object Lifetime 7.7 Using Dispose and Finalize 7.8 Using base and this 7.9 Using Value Types 7.10 Using Strings 7.11 Using Checked 7.12 Using Floating Point and Integral Types 7.13 Using Generics 7.14 Using Event Handlers 7.15 Using “var” 7.15.1 Examples 7.16 Using out and ref parameters 7.17 Error Handling 7.17.1 Strategies 7.17.2 Error Messages 7.17.3 The Try* Pattern 7.18 Exceptions 7.18.1 Defining Exceptions 7.18.2 Throwing Exceptions 7.18.3 Catching Exceptions 7.18.4 Wrapping Exceptions 7.18.5 Suppressing Exceptions 7.18.6 Specific Exception Types 7.19 Generated code 7.20 Setting Timeouts 7.21 Configuration & File System 7.22 Logging and Tracing 7.23 Performance 8 Processes 8.1 Documentation 8.1.1 Content 8.1.2 What to Document 8.2 Testing 8.3 Releases