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

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 (onecode@microsoft.com). 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: onecode@microsoft.com. 

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;