Tips for Releasing Sample Code
posted 12/23/2009 3:24:00 PM by Steve Andrews
When I’m learning a new technology, I’ll frequently download code samples that help me better understand the concepts. Often though I find myself frustrated by having to deal with formatting and extraneous information before even looking at the code. To that end I have some rules for releasing sample code.
Format Every Document
The keyboard shortcut for this is Ctrl+K+D. Nothing is more frustrating than looking at unformatted code.
Code should be ordered in the following structure from top to bottom:
- fields and automatic properties
- abstract methods
- abstract properties
Include a blank line before return statements and before and after decision blocks (including using, if, switch, while). In C#, opening and closing brackets should be on their own line.
Remove Excess Blank Lines
There should never be more than one consecutive blank line between any lines of code. With consecutive closing brackets as well as #endregion notations in C#, there should be no blank lines between them. There should also be no blank lines between fields or at the beginning or end of method or property bodies.
There should be one blank link between properties and methods to allow the user to see logical breaks in the code.
There should only be one class, interface or enumeration per file.
Always remove unnecessary XML comments from your code files. For example, this XML comment should be removed:
/// <param name="param"></param>
Import Namespace Placement
Import (C#) or using (VB) directives should be placed above the namespace. Also use the Organize Usings > Remove and Sort refactoring built-in to Visual Studio 2008 and Visual Studio 2010 to remove any unnecessary directives. This also helps to make the directives more readable.
Don’t manually wrap long lines of code. Visual Studio has a feature to allow a user to wrap long lines if they so choose.
Use automatic properties in .NET 3.0 code and above whenever possible.
These are a few of the rules. I’ll try to keep the list updated as I run across more frustrations.