微软一站式示例代码库编程规范

Original       http://1code.codeplex.com/releases/view/51868#DownloadId=148423

Translated  http://1codechs.codeplex.com/releases/view/51227#DownloadId=148734

 

Acknowledgement

Each chapter in this document has to acknowledge Dan Ruder, a Principal Escalation Engineer of Microsoft.  Dan carefully reviewed every word, and contributed review comments on significant portions of the book based on his more than 20 years’ programming experience.  Working with the nice man has been a special treat to me. 

I also thank four managers at Microsoft for continuously supporting and sponsoring the work: Vivian Luo, Allen Ding, Felix Wu and Mei Liang. 

This document wouldn’t contain the depth of technical details or the level of completeness it has without the input of the following key members of the All-In-One Code Framework project team.

Hongye Sun Jie Wang Ji Zhou Michael Sun Kira Qian Linda Liu

Allen Chen  Yi-Lun Luo Steven Cheng Wen-Jun Zhang

Some chapters derive from several Microsoft product teams’ coding standards. I appreciate their sharing.

The coding standards are continuously evolving. If you discover a new best practice or a topic that is not covered, please bring that to the attention of the All-In-One Code Framework Project Group ([email protected]). I look forward to appreciating your contributions. J

Disclaimer

This coding-standard document is provided "AS IS" without warranty of any kind, either expressed or implied, including but not limited to the implied warranties of merchantability and/or fitness for a particular purpose. 

Please feel free to use the coding standards when you are writing VC++/VC#/VB.NET code. It would be nice, however, if you could inform us that you are using the document, or send us your feedback. You may contact us at our email address: [email protected]. 

Table of Contents

1 Overview 1

1.1 Principles & Themes 1

1.2 Terminology 1

2 General Coding Standards 3

2.1 Clarity and Consistency 3

2.2 Formatting and Style 3

2.3 Using Libraries 5

2.4 Global Variables 5

2.5 Variable Declarations and Initalizations 5

2.6 Function Declarations and Calls 6

2.7 Statements 8

2.8 Enums 8

2.9 Whitespace 13

2.10 Braces 14

2.11 Comments 15

2.12 Regions 23

3 C++ Coding Standards 25

3.1 Compiler Options 25

3.2 Files and Structure 26

3.3 Naming Conventions 27

3.4 Pointers 30

3.5 Constants 31

3.6 Casting 32

3.7 Sizeof 32

3.8 Strings 33

3.9 Arrays 34

3.10 Macros 35

3.11 Functions 35

3.12 Structures 38

3.13 Classes 38

3.14 COM 44

3.15 Allocations 45

3.16 Errors and Exceptions 46

3.17 Resource Cleanup 48

3.18 Control Flow 50

4 .NET Coding Standards 54

4.1 Design Guidelines for Developing Class Libraries 54

4.2 Files and Structure 54

4.3 Assembly Properties 54

4.4 Naming Convensions 54

4.5 Constants 57

4.6 Strings 58

4.7 Arrays and Collections 59

4.8 Structures 61

4.9 Classes 62

4.10 Namespaces 65

4.11 Errors and Exceptions 65

4.12 Resource Cleanup 68

4.13 Interop 80

 

1 Overview

This document defines the native C++ and .NET coding standard for the All-In-One Code Framework project team.  This standard derives from the experience of product development efforts and is continuously evolving. If you discover a new best practice or a topic that is not covered, please bring that to the attention of the All-In-One Code Framework Project Group and have the conclusion added to this document.

No set of guidelines will satisfy everyone. The goal of a standard is to create efficiencies across a community of developers. Applying a set of well-defined coding standards will result in code with fewer bugs, and better maintainability. Adopting an unfamiliar standard may be awkward initially, but the pain fades quickly and the benefits are quickly realized, especially when you inherit ownership of others' code.

1.1 Principles & Themes

High-quality samples exhibit the following characteristics because customers use them as examples of best practices:

1. Understandable.  Samples must be clearly readable and straightforward.  They must showcase the key things they’re designed to demonstrate.  The relevant parts of a sample should be easy to reuse.  Samples should not contain unnecessary code.  They must include appropriate documentation.

2. Correct.  Samples must demonstrate properly how to perform the key things they are designed to teach.  They must compile cleanly, run correctly as documented, and be tested.

3. Consistent.  Samples should follow consistent coding style and layout to make the code easier to read.  Likewise, samples should be consistent with each other to make them easier to use together.  Consistency shows craftsmanship and attention to detail.

4. Modern.  Samples should demonstrate current practices such as use of Unicode, error handling, defensive programming, and portability.  They should use current recommendations for runtime library and API functions.  They should use recommended project & build settings.

5. Safe.  Samples must comply with legal, privacy, and policy standards.  They must not demonstrate hacks or poor programming practices.  They must not permanently alter machine state.  All installation and execution steps must be reversible.

6. Secure.  The samples should demonstrate how to use secure programming practices such as least privilege, secure versions of runtime library functions, and SDL-recommended project settings.

The proper use of programming practices, design, and language features determines how well samples can achieve these.  This code standard is designed to help you create samples that serve as “best practices” for customers to emulate.

1.2 Terminology

Through-out this document there will be recommendations or suggestions for standards and practices. Some practices are very important and must be followed, others are guidelines that are beneficial in certain scenarios but are not applicable everywhere. In order to clearly state the intent of the standards and practices that are discussed we will use the following terminology.

Wording	Intent	Justification
þ Do...	This standard or practice should be followed in all cases. If you think that your specific application is exempt, it probably isn't.	These standards are present to mitigate bugs.
ý Do Not...	This standard or practice should never be applied.
þ You should...	This standard or practice should be followed in most cases.	These standards are typically stylistic and attempt to promote a consistent and clear style.
ý You should not...	This standard or practice should not be followed, unless there's reasonable justification.
þ You can…	This standard or practice can be followed if you want to; it's not necessarily good or bad. There are probably implications to following the practice (dependencies, or constraints) that should be considered before adopting it.	These standards are typically stylistic, but are not ubiquitously adopted.

2 General Coding Standards

These general coding standards can be applied to all languages - they provide high-level guidance to the style, formatting and structure of your source code.

2.1 Clarity and Consistency

þ Do ensure that clarity, readability and transparency are paramount. These coding standards strive to ensure that the resultant code is easy to understand and maintain, but nothing beats fundamentally clear, concise, self-documenting code.

þ Do ensure that when applying these coding standards that they are applied consistently.

2.2 Formatting and Style

ý Do not use tabs. It's generally accepted across Microsoft that tabs shouldn't be used in source files - different text editors use different spacing to render tabs, and this causes formatting confusion. All code should be written using four spaces for indentation.

Visual Studio text editor can be configured to insert spaces for tabs.

þ You should limit the length of lines of code. Having overly long lines inhibits the readability of code. Break the code line when the line length is greater than column 78 for readability.  If column 78 looks too narrow, use column 86 or 90.

Visual C++ sample:

Visual C# sample:

Visual Basic sample:

þ Do use a fixed-width font, typically Courier New, in your code editor.

2.3 Using Libraries

ý Do not reference unnecessary libraries, include unnecessary header files, or reference unnecessary assemblies. Paying attention to small things like this can improve build times, minimize chances for mistakes, and give readers a good impression.

2.4 Global Variables

þ Do minimize global variables.  To use global variables properly, always pass them to functions through parameter values.  Never reference them inside of functions or classes directly because doing so creates a side effect that alters the state of the global without the caller knowing.  The same goes for static variables.  If you need to modify a global variable, you should do so either as an output parameter or return a copy of the global.

2.5 Variable Declarations and Initalizations

þ Do declare local variables in the minimum scope block that can contain them, typically just before use if the language allows; otherwise, at the top of that scope block.

þ Do initialize variables when they are declared.

þ Do declare and initialize/assign local variables on a single line where the language allows it. This reduces vertical space and makes sure that a variable does not exist in an un-initialized state or in a state that will immediately change. 

// C++ sample:

HANDLE hToken = NULL;

PSID pIntegritySid = NULL;

STARTUPINFO si = { sizeof(si) };

PROCESS_INFORMATION pi = { 0 };

// C# sample:

string name = myObject.Name;

int val = time.Hours;

' VB.NET sample:

Dim name As String = myObject.Name

Dim val As Integer = time.Hours

ý Do not declare multiple variables in a single line. One declaration per line is recommended since it encourages commenting, and could avoid confusion.  As a Visual C++ example,

Good:

CodeExample *pFirst = NULL;  // Pointer of the first element.

CodeExample *pSecond = NULL; // Pointer of the second element.

Bad:

CodeExample *pFirst, *pSecond;

The latter example is often mistakenly written as:

CodeExample *pFirst, pSecond;

Which is actually equivalent to:

CodeExample *pFirst;

CodeExample pSecond;

2.6 Function Declarations and Calls

The function/method name, return value and parameter list can take several forms. Ideally this can all fit on a single line. If there are many arguments that don't fit on a line those can be wrapped, many per line or one per line. Put the return type on the same line as the function/method name. For example,

Single Line Format:

// C++ function declaration sample:

HRESULT DoSomeFunctionCall(int param1, int param2, int *param3);

// C++ / C# function call sample:

hr = DoSomeFunctionCall(param1, param2, param3);

' VB.NET function call sample:

hr = DoSomeFunctionCall(param1, param2, param3)

Multiple Line Formats:

// C++ function declaration sample:

HRESULT DoSomeFunctionCall(int param1, int param2, int *param3, 

int param4, int param5);

// C++ / C# function call sample:

hr = DoSomeFunctionCall(param1, param2, param3, 

param4, param5);

' VB.NET function call sample:

hr = DoSomeFunctionCall(param1, param2, param3, _

    param4, param5)

When breaking up the parameter list into multiple lines, each type/parameter pair should line up under the preceding one, the first one being on a new line, indented one tab. Parameter lists for function/method calls should be formatted in the same manner. 

// C++ function declaration sample:

HRESULT DoSomeFunctionCall(

    HWND hwnd,    // You can comment parameters, too

    T1 param1,    // Indicates something

    T2 param2,    // Indicates something else

    T3 param3,    // Indicates more

    T4 param4,    // Indicates even more

    T5 param5);   // You get the idea

// C++ / C# function call sample:

hr = DoSomeFunctionCall(

    hwnd,

    param1,

    param2,

    param3,

    param4,

    param5);

' VB.NET function call sample:

hr = DoSomeFunctionCall( _

    hwnd, _

    param1, _

    param2, _

    param3, _

    param4, _

    param5)

þ Do order parameters, grouping the in parameters first, the out parameters last. Within the group, order the parameters based on what will help programmers supply the right values.  For example, if a function takes arguments named “left” and “right”, put “left” before “right” so that their place match their names. When designing a series of functions which take the same arguments, use a consistent order across the functions.  For example, if one function takes an input handle as the first parameter, all of the related functions should also take the same input handle as the first parameter.

2.7 Statements

ý Do not put more than one statement on a single line because it makes stepping through the code in a debugger much more difficult.

Good: 

// C++ / C# sample:

a = 1;

b = 2;

' VB.NET sample:

If (IsAdministrator()) Then

    Console.WriteLine("YES")

End If

Bad:

// C++ / C# sample:

a = 1; b = 2;

' VB.NET sample:

If (IsAdministrator()) Then Console.WriteLine("YES")

2.8 Enums

þ Do use an enum to strongly type parameters, properties, and return values that represent sets of values.

þ Do favor using an enum over static constants or “#define” values . An enum is a structure with a set of static constants. The reason to follow this guideline is because you will get some additional compiler and reflection support if you define an enum versus manually defining a structure with static constants.

Good: 

// C++ sample: 

enum Color

{

    Red,

    Green,

    Blue

};

// C# sample:

public enum Color

{

    Red,

    Green,

    Blue

}

' VB.NET sample:

Public Enum Color

    Red

    Green

    Blue

End Enum

Bad: 

// C++ sample:

const int RED   = 0;

const int GREEN = 1;

const int BLUE  = 2;

#define RED       0

#define GREEN     1

#define BLUE      2

// C# sample:

public static class Color

{

    public const int Red = 0;

    public const int Green = 1;

    public const int Blue = 2;

}

' VB.NET sample:

Public Class Color

    Public Const Red As Integer = 0

    Public Const Green As Integer = 1

    Public Const Blue As Integer = 2

End Class

ý Do not use an enum for open sets (such as the operating system version, names of your friends, etc.).

þ Do provide a value of zero on simple enums. Consider calling the value something like “None.” If such value is not appropriate for this particular enum, the most common default value for the enum should be assigned the underlying value of zero.

// C++ sample: 

enum Compression

{

    None = 0,

    GZip,

    Deflate

};

// C# sample:

public enum Compression

{

    None = 0,

    GZip,

    Deflate

}

' VB.NET sample:

Public Enum Compression

    None = 0

    GZip

    Deflate

End Enum

ý Do not use Enum.IsDefined for enum range checks in .NET. There are really two problems with Enum.IsDefined. First it loads reflection and a bunch of cold type metadata, making it a surprisingly expensive call. Second, there is a versioning issue here. 

Good: 

// C# sample:

if (c > Color.Black || c < Color.White)

{

    throw new ArgumentOutOfRangeException(...);

}

' VB.NET sample:

If (c > Color.Black Or c < Color.White) Then

    Throw New ArgumentOutOfRangeException(...);

End If

Bad: 

// C# sample:

if (!Enum.IsDefined(typeof(Color), c))

{

    throw new InvalidEnumArgumentException(...);

}

' VB.NET sample:

If Not [Enum].IsDefined(GetType(Color), c) Then

    Throw New ArgumentOutOfRangeException(...);

End If

2.8.1 Flag Enums

Flag enums are designed to support bitwise operations on the enum values. A common example of the flags enum is a list of options.

þ Do apply the System.FlagsAttribute to flag enums in .NET. Do not apply this attribute to simple enums.

þ Do use powers of two for the flags enum values so they can be freely combined using the bitwise OR operation. For example,

// C++ sample:

enum AttributeTargets 

{

    Assembly = 0x0001,

    Class    = 0x0002,

    Struct   = 0x0004

    ...

};

// C# sample:

[Flags]

public enum AttributeTargets 

{

    Assembly = 0x0001,

    Class    = 0x0002,

    Struct   = 0x0004,

    ...

}

' VB.NET sample:

<Flags()> _

Public Enum AttributeTargets

    Assembly = &H1

    Class = &H2

    Struct = &H4

    ...

End Enum

þ You should provide special enum values for commonly used combinations of flags. Bitwise operations are an advanced concept and should not be required for simple tasks. FileAccess.ReadWrite is an example of such a special value. However, you should not create flag enums where certain combinations of values are invalid.

// C++ sample:

enum FileAccess

{

    Read = 0x1,

    Write = 0x2,

    ReadWrite = Read | Write

};

// C# sample:

[Flags]

public enum FileAccess

{

    Read = 0x1,

    Write = 0x2,

    ReadWrite = Read | Write

}

' VB.NET sample:

<Flags()> _

Public Enum FileAccess

    Read = &H1

    Write = &H2

    ReadWrite = Read Or Write

End Enum

ý You should not use flag enum values of zero, unless the value represents “all flags are cleared” and is named appropriately as “None”. The following C# example shows a common implementation of a check that programmers use to determine if a flag is set (see the if-statement below). The check works as expected for all flag enum values except the value of zero, where the Boolean expression always evaluates to true.

Bad: 

[Flags]

public enum SomeFlag 

{

    ValueA = 0,  // This might be confusing to users

    ValueB = 1,

    ValueC = 2,

    ValueBAndC = ValueB | ValueC,

}

SomeFlag flags = GetValue();

if ((flags & SomeFlag.ValueA) == SomeFlag.ValueA) 

{ 

    ...

}

Good: 

[Flags]

public enum BorderStyle 

{

    Fixed3D           = 0x1,  

    FixedSingle       = 0x2,

    None              = 0x0

}

if (foo.BorderStyle == BorderStyle.None)

{ 

    ...

}

2.9 Whitespace

2.9.1 Blank Lines

þ You should use blank lines to separate groups of related statements.  Omit extra blank lines that do not make the code easier to read.  For example, you can have a blank line between variable declarations and code.

Good: 

// C++ sample:

void ProcessItem(const Item& item)

{

    int counter = 0;

    if(...)

    {

    }

}

Bad: 

// C++ sample:

void ProcessItem(const Item& item)

{

    int counter = 0;

    // Implementation starts here

    //

    if(...)

    {

    }

}

In this example of bad usage of blank lines, there are multiple blank lines between the local variable declarations, and multiple blank likes after the ‘if’ block.

þ You should use two blank lines to separate method implementations and class declarations.

2.9.2 Spaces

Spaces improve readability by decreasing code density. Here are some guidelines for the use of space characters within code:

þ You should use spaces within a line as follows.

Good: 

// C++ / C# sample:

CreateFoo();               // No space between function name and parenthesis

Method(myChar, 0, 1);      // Single space after a comma

x = array[index];          // No spaces inside brackets

while (x == y)             // Single space before flow control statements

if (x == y)                // Single space separates operators

' VB.NET sample:

CreateFoo()                ' No space between function name and parenthesis

Method(myChar, 0, 1)       ' Single space after a comma

x = array(index)           ' No spaces inside brackets

While (x = y)              ' Single space before flow control statements

If (x = y) Then            ' Single space separates operators

Bad:

// C++ / C# sample:

CreateFoo ();              // Space between function name and parenthesis

Method(myChar,0,1);        // No spaces after commas

CreateFoo( myChar, 0, 1 ); // Space before first arg, after last arg

x = array[ index ];        // Spaces inside brackets

while(x == y)              // No space before flow control statements

if (x==y)                  // No space separates operators

' VB.NET sample:

CreateFoo ()               ' Space between function name and parenthesis

Method(myChar,0,1)         ' No spaces after commas

CreateFoo( myChar, 0, 1 )  ' Space before first arg, after last arg

x = array( index )         ' Spaces inside brackets

While(x = y)               ' No space before flow control statements

If (x=y) Then              ' No space separates operators

2.10 Braces

þ Do use Allman bracing style in All-In-One Code Framework code samples. 

The Allman style is named after Eric Allman. It is sometimes referred to as "ANSI style". The style puts the brace associated with a control statement on the next line, indented to the same level as the control statement. Statements within the braces are indented to the next level.

Good: 

// C++ / C# sample:

if (x > 5)

{

    y = 0;

}

' VB.NET sample:

If (x > 5) Then

    y = 0

End If

Bad (in All-In-One Code Framework samples):

// C++ / C# sample:

if (x > 5) {

    y = 0;

}

þ You should use braces around single line conditionals. Doing this makes it easier to add code to these conditionals in the future and avoids ambiguities should the tabbing of the file become disturbed.

Good: 

// C++ / C# sample:

if (x > 5)

{

    y = 0;

}

' VB.NET sample:

If (x > 5) Then

    y = 0

End If

Bad:

// C++ / C# sample:

if (x > 5) y = 0;

' VB.NET sample:

If (x > 5) Then y = 0

2.11 Comments

þ You should use comments that summarize what a piece of code is designed to do and why. Do not use comments to repeat the code.

Good:

// Determine whether system is running Windows Vista or later operating 

// systems (major version >= 6) because they support linked tokens, but 

// previous versions (major version < 6) do not.

Bad:

// The following code sets the variable i to the starting value of the 

// array.  Then it loops through each item in the array.

þ You should use ‘//’ comments instead of ‘/* */’ for comments for C++ and C# code comments. The single-line syntax (// …) is preferred even when a comment spans multiple lines.

// Determine whether system is running Windows Vista or later operating 

// systems (major version >= 6) because they support linked tokens, but 

// previous versions (major version < 6) do not.

if (Environment.OSVersion.Version.Major >= 6)

{

}

' Get and display the process elevation information (IsProcessElevated) 

' and integrity level (GetProcessIntegrityLevel). The information is not 

' available on operating systems prior to Windows Vista.

If (Environment.OSVersion.Version.Major >= 6) Then

End If

þ You should indent comments at the same level as the code they describe.

þ You should use full sentences with initial caps, a terminating period and proper punctuation and spelling in comments.

Good:

// Intialize the components on the Windows Form.

InitializeComponent();

' Intialize the components on the Windows Form.

InitializeComponent()

Bad:

//intialize the components on the Windows Form.

InitializeComponent();

'intialize the components on the Windows Form

InitializeComponent()

2.11.1 Inline Code Comments

Inline comments should be included on their own line and should be indented at the same level as the code they are commenting on, with a blank line before, but none after. Comments describing a block of code should appear on a line by themselves, indented as the code they describe, with one blank line before it and one blank line after it.  For example:

if (MAXVAL >= exampleLength)

{

    // Reprort the error.

    ReportError(GetLastError());

    // The value is out of range, we cannot continue.

    return E_INVALIDARG;

}

Inline comments are permissible on the same line as the actual code only when giving a brief description of a structure member, class member variable, parameter, or a short statement.   In this case it is a good idea to align the comments for all variables.  For example:

class Example

{

public:

    ...

    void TestFunction

{

    ...

        do

        {

            ...

        }

        while (!fFinished); // Continue if not finished.

    }

private:

    int m_length;     // The length of the example

    float m_accuracy; // The accuracy of the example

};

ý You should not drown your code in comments. Commenting every line with obvious descriptions of what the code does actually hinders readability and comprehension. Single-line comments should be used when the code is doing something that might not be immediately obvious.

The following example contains many unnecessary comments:

Bad:

// Loop through each item in the wrinkles array

for (int i = 0; i <= nLastWrinkle; i++)

{

    Wrinkle *pWrinkle = apWrinkles[i];    // Get the next wrinkle

    if (pWrinkle->IsNew() &&              // Process if it’s a new wrinkle

        nMaxImpact < pWrinkle->GetImpact()) // And it has the biggest impact

    {

        nMaxImpact = pWrinkle->GetImpact(); // Save its impact for comparison

        pBestWrinkle = pWrinkle;        // Remember this wrinkle as well

    }

}

A better implementation would be:

Good:

// Loop through each item in the wrinkles array, find the Wrinkle with 

// the largest impact that is new, and store it in ‘pBestWrinkle’.

for (int i = 0; i <= nLastWrinkle; i++)

{

    Wrinkle *pWrinkle = apWrinkles[i];

    if (pWrinkle->IsNew() && nMaxImpact < pWrinkle->GetImpact())

    {

        nMaxImpact = pWrinkle->GetImpact();

        pBestWrinkle = pWrinkle;

    }

}

þ You should add comments to call out non-intuitive or behavior that is not obvious from reading the code.

2.11.2 File Header Comments

þ Do have a file header comment at the start of every human-created code file. The header comment templates are as follows:

VC++ and VC# file header comment template:

/****************************** Module Header ******************************/

Module Name:  <File Name>

Project:      <Sample Name>

Copyright (c) Microsoft Corporation.