微软一站式示例代码库编程规范
来源：互联网 发布：淘宝客人工服务电话 编辑：程序博客网 时间：2024/05/16 18:09
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 SunJie WangJi ZhouMichael SunKira QianLinda Liu
Allen Chen Yi-Lun LuoSteven ChengWen-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
1Overview1
1.1Principles & Themes1
1.2Terminology1
2General Coding Standards3
2.1Clarity and Consistency3
2.2Formatting and Style3
2.3Using Libraries5
2.4Global Variables5
2.5Variable Declarations and Initalizations5
2.6Function Declarations and Calls6
2.7Statements8
2.8Enums8
2.9Whitespace13
2.10Braces14
2.11Comments15
2.12Regions23
3C++ Coding Standards25
3.1Compiler Options25
3.2Files and Structure26
3.3Naming Conventions27
3.4Pointers30
3.5Constants31
3.6Casting32
3.7Sizeof32
3.8Strings33
3.9Arrays34
3.10Macros35
3.11Functions35
3.12Structures38
3.13Classes38
3.14COM44
3.15Allocations45
3.16Errors and Exceptions46
3.17Resource Cleanup48
3.18Control Flow50
4.NET Coding Standards54
4.1Design Guidelines for Developing Class Libraries54
4.2Files and Structure54
4.3Assembly Properties54
4.4Naming Convensions54
4.5Constants57
4.6Strings58
4.7Arrays and Collections59
4.8Structures61
4.9Classes62
4.10Namespaces65
4.11Errors and Exceptions65
4.12Resource Cleanup68
4.13Interop80
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;
