（微软一站式代码示例）编程规范(5)

Page 17

2.11 注释

?您应该使用注释来解释一段代码的设计意图。一定不要让注释仅仅是重复代码。

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.

?您应该使用 ‘//’ 注释方式，而不是 ‘/* */’来为 C++ 和 C# 代码作注释。即使注释跨越多行代码，单行注释语法（// …）仍然是首选。

// 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 EndIf

?您应该将注释缩进为被其描述的代码的同一级。

?您应该在注释中使用首字母大写的完整的句子，以及适当的标点符号和拼写。

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.

? 2015 Microsoft Corporation. All rights reserved. All-In-One Code Framework （http://1code.codeplex.com）

Page 18

InitializeComponent（）;

'intialize the components on the Windows Form InitializeComponent（）

2.11.1 内联代码注释

内联注释应该置于独立行，并与所描述的代码具有相同的缩进。其之前需放置一个空行。其之后不需要空行。描述代码块的注释应该置于独立行，与所描述的代码具有相同的缩进。其之前和之后都有一个空行。举例:

if（MAXVAL >= exampleLength） {

// Reprort the error.

ReportError（GetLastError（））;

// The value is out of range, we cannot continue. return E_INVALIDARG; }

当内联注释只为结构体，类成员变量，参数和短语句做描述时，则内联注释允许出现在和实际代码的同一行。在本例中，最好将所有变量的注释对齐。

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 };

? 2015 Microsoft Corporation. All rights reserved. All-In-One Code Framework （http://1code.codeplex.com）

Page 19

?您不应该在代码中留有过多注释。如果每一行代码都有注释，便会影响到可读性和可理解性。单行注释应该用于代码的行为并不是那么明显易懂的情况。

如下代码包含多余注释：

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 } }

更好的实现如下:

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; } }

?您应该为那些仅通过阅读很难理解其意图的代码添加注释。 2.11.2 文件头注释

?一定请为每一份手写代码文件加入文件头注释。如下为文件头注释:

? 2015 Microsoft Corporation. All rights reserved. All-In-One Code Framework （http://1code.codeplex.com）

Page 20

VC++ 和 VC# 文件头注释模板:

/****************************** Module Header ******************************\\ Module Name: Project:

Copyright （c） Microsoft Corporation.

This source is subject to the Microsoft Public License. See http://www.microsoft.com/opensource/licenses.mspx#Ms-PL. All other rights reserved.

THIS CODE AND INFORMATION IS PROVIDED \EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A PARTICULAR PURPOSE. \\***************************************************************************/

VB.NET 文件头注释模板:

'***************************** Module Header *******************************\\ ' Module Name: ' Project:

' Copyright （c） Microsoft Corporation. '

' '

' This source is subject to the Microsoft Public License. ' See http://www.microsoft.com/opensource/licenses.mspx#Ms-PL. ' All other rights reserved. '

' THIS CODE AND INFORMATION IS PROVIDED \' EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE IMPLIED ' WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A PARTICULAR PURPOSE. '***************************************************************************/

举例,

/****************************** Module Header ******************************\\ Module Name: CppUACSelfElevation.cpp Project: CppUACSelfElevation Copyright （c） Microsoft Corporation.

User Account Control （UAC） is a new security component in Windows Vista and

? 2015 Microsoft Corporation. All rights reserved. All-In-One Code Framework （http://1code.codeplex.com）

Page 21

newer operating systems. With UAC fully enabled, interactive administrators normally run with least user privileges. This example demonstrates how to check the privilege level of the current process, and how to self-elevate the process by giving explicit consent with the Consent UI.

This source is subject to the Microsoft Public License. See http://www.microsoft.com/opensource/licenses.mspx#Ms-PL. All other rights reserved.

THIS CODE AND INFORMATION IS PROVIDED \EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A PARTICULAR PURPOSE.

\\***************************************************************************/

2.11.3 类注释

?您应该为每一个重要的类或结构体作注释。注释的详细程度应该视代码的用户群而定。

C++ 类注释模板:

//

// NAME: class

// DESCRIPTION: //

C#和 VB.NET 使用.NET 描述性 XML文档化注释。当您编译.NET 项目，并带有/doc 命令时，编译器会在源代码中搜索 XML 标签，并生成XML文档。

C# 类注释模板:

///

/// ///

VB.NET 类注释模板:

'''

''' '''

? 2015 Microsoft Corporation. All rights reserved. All-In-One Code Framework （http://1code.codeplex.com）