Sign In

Brad Abrams
Design Guidelines, Managed code and the .NET Framework

MSDN Blogs > Brad Abrams > Internal Coding Guidelines Translate This Page
Internal Coding Guidelines Translate this page
RATE THIS
BradA 26 Jan 2005 10:13 PM 142 Sp an ish
Microsoft® Translator

Table of Contents
1. Introduction.......................................................................................................................................... 1 Options
2. Style Guidelines.................................................................................................................................... 2 Blog Home
2.1 Tabs & Indenting................................................................................................................................ 2 Email Blog Author
Share this
2.2 Bracing............................................................................................................................................... 2
RSS for posts
2.3 Commenting........................................................................................................................................ 2 Atom
RSS for comments
2.3.1 Documentation Comments............................................................................................................. 2
2.3.2 Comment Style............................................................................................................................. 3
Search
2.4 Spacing............................................................................................................................................... 3
2.5 Naming............................................................................................................................................... 4
Search this blog Search all blogs
2.6 Naming Conventions............................................................................................................................ 4
2.6.1 Interop Classes............................................................................................................................. 4 Tags
2.7 File Organization................................................................................................................................. 5
.NET Framework .NETFx3.0
AJAX ASP.NET Atlas BCL Blogging
1. Introduction CLR Framework Design
First, read the .NET Framework Design Guidelines. Almost all naming conventions, casing rules, etc., are spelled out
in this document. Unlike the Design Guidelines document, you should treat this document as a set of suggested Guidelines Mix07 Mix08 MEF Mix09
guidelines. These generally do not effect the customer view so they are not required.
Mix10 New Guideline PDC Program
2. Style Guidelines Manager Random RIAServices
2.1 Tabs & Indenting
Tab characters (\0x09) should not be used in code. All indentation should be done with 4 space characters. Silverlight SLAR Softw are Development

2.2 Bracing TechEd WinForms WPF

Open braces should always be at the beginning of the line after the statement that begins the block. Contents of
the brace should be indented by 4 spaces. For example:
if (someExpression) Archive
{
DoSomething(); April 2010 (2)
} March 2010 (16)
else February 2010 (1)
{
January 2010 (1)
DoSomethingElse();
} December 2009 (3)
November 2009 (6)
“case” statements should be indented from the switch statement like this: October 2009 (10)
switch (someExpression)
September 2009 (8)
{
August 2009 (11)
case 0: July 2009 (24)
DoSomething(); June 2009 (7)
break;
May 2009 (5)
case 1: April 2009 (8)
DoSomethingElse(); March 2009 (15)
break; February 2009 (6)
case 2: January 2009 (5)
{ December 2008 (6)
int n = 1; November 2008 (13)
DoAnotherThing(n); October 2008 (13)
}
September 2008 (7)
break;
} August 2008 (11)
July 2008 (7)

converted by Web2PDFConvert.com
Braces should never be considered optional. Even for single statement blocks, you should always use braces. This June 2008 (13)
increases code readability and maintainability.
May 2008 (7)
for (int i=0; i<100; i++) { DoSomething(i); }
April 2008 (11)
2.3 Single line statements March 2008 (21)
Single line statements can have braces that begin and end on the same line. February 2008 (12)
public class Foo January 2008 (14)
{ December 2007 (13)
int bar;
November 2007 (13)
public int Bar October 2007 (21)
{ September 2007 (7)
get { return bar; } August 2007 (13)
set { bar = value; }
July 2007 (10)
}
June 2007 (25)
} May 2007 (18)
It is suggested that all control structures (if, while, for, etc.) use braces, but it is not required. April 2007 (15)
March 2007 (15)
2.4 Commenting February 2007 (6)
Comments should be used to describe intention, algorithmic overview, and/or logical flow. It would be ideal, if
from reading the comments alone, someone other than the author could understand a function’s intended January 2007 (15)
behavior and general operation. While there are no minimum comment requirements and certainly some very December 2006 (8)
small routines need no commenting at all, it is hoped that most routines will have comments reflecting the November 2006 (12)
programmer’s intent and approach. October 2006 (13)
2.4.1 Copyright notice September 2006 (8)
Each file should start with a copyright notice. To avoid errors in doc comment builds, you don’t want to use triple- August 2006 (5)
slash doc comments, but using XML makes the comments easy to replace in the future. Final text will vary by July 2006 (12)
product (you should contact legal for the exact text), but should be similar to: June 2006 (15)
//-----------------------------------------------------------------------
May 2006 (12)
// <copyright file="ContainerControl.cs" company="Microsoft">
// Copyright (c) Microsoft Corporation. All rights reserved. April 2006 (10)
// </copyright> March 2006 (15)
//----------------------------------------------------------------------- February 2006 (14)
January 2006 (13)
2.4.2 Documentation Comments December 2005 (7)
All methods should use XML doc comments. For internal dev comments, the <devdoc> tag should be used.
November 2005 (18)
public class Foo
{ October 2005 (16)
September 2005 (31)
/// <summary>Public stuff about the method</summary> August 2005 (22)
/// <param name=”bar”>What a neat parameter!</param>
July 2005 (15)
/// <devdoc>Cool internal stuff!</devdoc>
/// June 2005 (14)
public void MyMethod(int bar) { … } May 2005 (17)
April 2005 (25)
}
March 2005 (28)
However, it is common that you would want to move the XML documentation to an external file – for that, use the February 2005 (22)
<include> tag. January 2005 (29)
public class Foo December 2004 (18)
{
November 2004 (17)
/// <include file='doc\Foo.uex' path='docs/doc[@for="Foo.MyMethod"]/*' /> October 2004 (25)
/// September 2004 (16)
public void MyMethod(int bar) { … } August 2004 (28)
} July 2004 (17)
June 2004 (20)
UNDONE§ there is a big doc with all the comment tags we should be using… where is that?
May 2004 (28)
2.4.3 Comment Style April 2004 (31)
The // (two slashes) style of comment tags should be used in most situations. Where ever possible, place March 2004 (29)
comments above the code instead of beside it. Here are some examples: February 2004 (30)
// This is required for WebClient to work through the proxy
January 2004 (35)
GlobalProxySelection.Select = new WebProxy("http://itgproxy");
December 2003 (17)
November 2003 (28)
// Create object to access Internet resources October 2003 (43)
//
September 2003 (25)
WebClient myClient = new WebClient();
August 2003 (21)
Comments can be placed at the end of a line when space allows: July 2003 (26)
public class SomethingUseful June 2003 (9)
{
May 2003 (14)
private int itemHash; // instance member
private static bool hasDoneSomething; // static member April 2003 (50)
}

converted by Web2PDFConvert.com
2.5 Spacing
Spaces improve readability by decreasing code density. Here are some guidelines for the use of space characters
within code:
Do use a single space after a comma between function arguments.
Right: Console.In.Read(myChar, 0, 1);
Wrong: Console.In.Read(myChar,0,1);
Do not use a space after the parenthesis and function arguments
Right: CreateFoo(myChar, 0, 1)
Wrong: CreateFoo( myChar, 0, 1 )
Do not use spaces between a function name and parenthesis.
Right: CreateFoo()
Wrong: CreateFoo ()
Do not use spaces inside brackets.
Right: x = dataArray[index];
Wrong: x = dataArray[ index ];
Do use a single space before flow control statements
Right: while (x == y)
Wrong: while(x==y)
Do use a single space before and after comparison operators
Right: if (x == y)
Wrong: if (x==y)

2.6 Naming
Follow all .NET Framework Design Guidelines for both internal and external members. Highlights of these include:
Do not use Hungarian notation
Do not use a prefix for member variables (_, m_, s_, etc.). If you want to distinguish between local and
member variables you should use “this.” in C# and “Me.” in VB.NET.
Do use camelCasing for member variables
Do use camelCasing for parameters
Do use camelCasing for local variables
Do use PascalCasing for function, property, event, and class names
Do prefix interfaces names with “I”
Do not prefix enums, classes, or delegates with any letter

The reasons to extend the public rules (no Hungarian, no prefix for member variables, etc.) is to produce a
consistent source code appearance. In addition a goal is to have clean readable source. Code legibility should be a
primary goal.
2.7 Naming Conventions
2.7.1 Interop Classes
Classes that are there for interop wrappers (DllImport statements) should follow the naming convention below:
NativeMethods – No suppress unmanaged code attribute, these are methods that can be used anywhere
because a stack walk will be performed.
UnsafeNativeMethods – Has suppress unmanaged code attribute. These methods are potentially
dangerous and any caller of these methods must do a full security review to ensure that the usage is safe
and protected as no stack walk will be performed.
SafeNativeMethods – Has suppress unmanaged code attribute. These methods are safe and can be used
fairly safely and the caller isn’t needed to do full security reviews even though no stack walk will be
performed.
class NativeMethods
{
private NativeMethods() {}

[DllImport(“user32”)]
internal static extern void FormatHardDrive(string driveName);
}
[SuppressUnmanagedCode]
class UnsafeNativeMethods
{
private UnsafeNativeMethods() {}
[DllImport(“user32”)]
internal static extern void CreateFile(string fileName);
}

[SuppressUnmanagedCode]
class SafeNativeMethods
{
private SafeNativeMethods() {}

[DllImport(“user32”)]
internal static extern void MessageBox(string text);
}

converted by Web2PDFConvert.com
All interop classes must be private, and all methods must be internal. In addition a private constructor should be
provided to prevent instantiation.
2.8 File Organization
Source files should contain only one public type, although multiple internal classes are allowed
Source files should be given the name of the public class in the file
Directory names should follow the namespace for the class
For example, I would expect to find the public class “System.Windows.Forms.Control” in
“System\Windows\Forms\Control.cs”…
Classes member should be alphabetized, and grouped into sections (Fields, Constructors, Properties,
Events, Methods, Private interface implementations, Nested types)
Using statements should be inside the namespace declaration.
namespace MyNamespace
{
using System;
public class MyClass : IFoo
{

// fields
int foo;
// constructors
public MyClass() { … }
// properties
public int Foo { get { … } set { … } }
// events
public event EventHandler FooChanged { add { … } remove { … } }

// methods
void DoSomething() { … }
void FindSomethind() { … }

//private interface implementations

void IFoo.DoSomething() { DoSomething(); }
// nested types
class NestedType { … }
}
}

Pages

Comments

Adarsh Bhat 27 Jan 2005 12:37 AM

This is really useful. Thanks.

Sam 27 Jan 2005 1:21 AM

>Source files should contain only one public type

So if I have a class Foo, and it got some enum as parameter of type Bar that is only used in Foo, shall I
make a source file for Foo and one for Bar instead of putting both in one?

If thats too confusing, an example:

should it look like this:

--
Foo.cs:
class Foo
{
public enum Bar { fast, exact)
public Foo( Bar how)
{
// initialize Foo according to Bar
}

converted by Web2PDFConvert.com
}
--
or like that:
--
Bar.cs
public enum Bar { fast, exact)
Foo.cs:
class Foo
{
public Foo( Bar how)
{
// initialize Foo according to Bar
}
}
--

And what about delegates? EventArgs?

Sam

Samuel Jack 27 Jan 2005 1:51 AM

There seems to be a conflict between these two guidelines:

"Braces should never be considered optional. Even for single statement blocks, you should always use
braces."

and a few lines later

"It is suggested that all control structures (if, while, for, etc.) use braces, but it is not required."

Matt Hall's Blog 27 Jan 2005 3:51 AM

Matt Hall's Blog 27 Jan 2005 3:56 AM

Di .NET e di altre amenita' 27 Jan 2005 3:57 AM

mihailik 27 Jan 2005 4:07 AM

My point on braces omitting:

DO omit braces around simple single-statement body:

// nice
if( ... )
x = y+z;

// ugly
if( ... )
{
x = y+z;
}

DO NOT omit braces around compound statements:

// ugly
if( ... )
foreach( ... )
x = y+z;

// nice

if( ... )
{
foreach( ... )
x = y+z;
}

DO NOT omit braces around if-part or else-part if other part embraced:

// ugly

converted by Web2PDFConvert.com
if( ... )
x = y+z;
else
{
a = b+c;
i++;
}

// nice
if( ... )
{
x = y+z;
}
else
{
a = b+c;
i++;
}

This rules makes readability cleaner. IMHO.

mihailik 27 Jan 2005 4:11 AM

You didn't state that. Do you really use camelCase for private constants?

Kevin Westhead 27 Jan 2005 4:37 AM

Sam, I think if you choose to follow the guidelines posted here then you would create two files. You
would also create a separate file for each public delegate and each EventArgs-derived type. This means
that if you know the full name of the public type then you can easily find the file where the source is
defined.

AppDomain is a pretty interesting example in the sscli since it exposes three EventArgs-derived types:

AssemblyLoadEventArgs
ResolveEventArgs
UnhandledExceptionEventArgs

and three delegates:

AssemblyLoadEventHandler
ResolveEventHandler
UnhandledExceptionEventHandler

The first two in each set are defined in \sscli\clr\src\bcl\system\appdomain.cs but the last ones are
defined in \sscli\clr\src\bcl\system\unhandledexceptioneventargs.cs and
\sscli\clr\src\bcl\system\unhandledexceptioneventhandler.cs.

Ultimately though, the important thing (as far as naming is concerned) is that each type conforms to
the naming guidelines for events.

Sam 27 Jan 2005 4:51 AM

Thanks Kevin - so your AppDomain example does not behave like the above guidelines for public types
would propose, if I understand you correctly?

And, another thing, can I conclude that public types should not be nested? Example would be a class
that throws a special exception.
I could put the class declaration for the exception inside the class that might throw it, put then it wont
be in its own source file.

And probably nesting public types aint good anyway (I'm just searching for some reasons why to
oppose to it, right now it's just a hunch I have that nesting public types might be no good)?

Stuart 27 Jan 2005 4:54 AM

Are there any specific guidelines for naming gui controls? Would you use just use the type or an
abbreviation of the type as a suffix?

Label somethingLabel;
or
Label somethingLbl;

converted by Web2PDFConvert.com
 G. Man 27 Jan 2005 6:35 AM
>Source files should contain only one public type,

I disagree with this also. It sounds good until you actually try to enforce it. If I have a class which fires
some events that have their own FooEventArgs classes, I'm going to define those right there in the file.
It's stupid to create another file for those.

Kevin Westhead 27 Jan 2005 7:02 AM

G. Man, what happens when another class comes along that also raises an event taking a FooEventArgs,
i.e. you re-use the class somewhere else? Would you split it into its own file then?

Sam, you can read the guidelines for nested types here:

http://msdn.microsoft.com/library/en-us/cpgenref/html/cpconusingnestedtypes.asp?frame=false

You can also view the FxCop rule on the subject here:

http://www.gotdotnet.com/team/fxcop/Docs/Rules/Design/NestedTypesShouldNotBeVisible.html

Grim 27 Jan 2005 9:05 AM

I usually break delegates/event args into matched pairs:

ServerEvent.cs:<pre>
public delegate void ServerEventHandler(object sender, ServerEventArgs e);

public class ServerEventArgs : EventArgs

{
private IServer server;

public ServerEventArgs(IServer server)

{
this.server = server;
}

public IServer Server {get{return this.server;}}

}
</pre>

DataEvent.cs:<pre>
public delegate void DataEventHandler(Object sender, DataEventArgs e);

public class DataEventArgs : EventArgs

{
private object data = null;

public DataEventArgs(object data)

{
this.data = data;
}

public object Data

{
get{return this.data;}
}
}
</pre>

andyBlog 27 Jan 2005 9:44 AM

MS coding style

1 2 3 4 5 »

© 2011 Microsoft Corporation. Terms of Use Trademarks Privacy Statement Report Abuse

converted by Web2PDFConvert.com