'Coding Guideline'에 해당되는 글 1건

  1. 2008.03.04 Internal Coding Guidelines
Study/MSDN2008. 3. 4. 23:24

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

Posted by 굥쓰