Internal Coding Guidelines
Table of Contents
1. Introduction.......................................................................................................................................... 1
2. Style Guidelines.................................................................................................................................... 2
2.1 Tabs & Indenting................................................................................................................................ 2
2.2 Bracing............................................................................................................................................... 2
2.3 Commenting........................................................................................................................................ 2
2.3.1 Documentation Comments............................................................................................................. 2
2.3.2 Comment Style............................................................................................................................. 3
2.4 Spacing............................................................................................................................................... 3
2.5 Naming............................................................................................................................................... 4
2.6 Naming Conventions............................................................................................................................ 4
2.6.1 Interop Classes............................................................................................................................. 4
2.7 File Organization................................................................................................................................. 5
1. Introduction
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. These generally do not effect the customer view so they are not required.
2. Style Guidelines
2.1 Tabs & Indenting
Tab characters (\0x09) should not be used in code. All indentation should be done with 4 space characters.
2.2 Bracing
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)
{
DoSomething();
}
else
{
DoSomethingElse();
}
“case” statements should be indented from the switch statement like this:
switch (someExpression)
{
case 0:
DoSomething();
break;
case 1:
DoSomethingElse();
break;
case 2:
{
int n = 1;
DoAnotherThing(n);
}
break;
}
Braces should never be considered optional. Even for single statement blocks, you should always use braces. This increases code readability and maintainability.
for (int i=0; i<100; i++) { DoSomething(i); }
2.3 Single line statements
Single line statements can have braces that begin and end on the same line.
public class Foo
{
int bar;
public int Bar
{
get { return bar; }
set { bar = value; }
}
}
It is suggested that all control structures (if, while, for, etc.) use braces, but it is not required.
2.4 Commenting
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 behavior and general operation. While there are no minimum comment requirements and certainly some very small routines need no commenting at all, it is hoped that most routines will have comments reflecting the programmer’s intent and approach.
2.4.1 Copyright notice
Each file should start with a copyright notice. To avoid errors in doc comment builds, you don’t want to use triple-slash doc comments, but using XML makes the comments easy to replace in the future. Final text will vary by product (you should contact legal for the exact text), but should be similar to:
//-----------------------------------------------------------------------
// <copyright file="ContainerControl.cs" company="Microsoft">
// Copyright (c) Microsoft Corporation. All rights reserved.
// </copyright>
//-----------------------------------------------------------------------
2.4.2 Documentation Comments
All methods should use XML doc comments. For internal dev comments, the <devdoc> tag should be used.
public class Foo
{
/// <summary>Public stuff about the method</summary>
/// <param name=”bar”>What a neat parameter!</param>
/// <devdoc>Cool internal stuff!</devdoc>
///
public void MyMethod(int bar) { … }
}
However, it is common that you would want to move the XML documentation to an external file – for that, use the <include> tag.
public class Foo
{
/// <include file='doc\Foo.uex' path='docs/doc[@for="Foo.MyMethod"]/*' />
///
public void MyMethod(int bar) { … }
출처 : http://blogs.msdn.com/brada/articles/361363.aspx
