Page 22
举例,
//
// NAME: class CodeExample
// DESCRIPTION: The CodeExample class represents an example of code, and // tracks the length and complexity of the example. //
class CodeExample { ... };
///
/// The CodeExample class represents an example of code, and tracks /// the length and complexity of the example. ///
publicclassCodeExample { ... }
2.11.4 函数注释
?您应该为所有重要的Public或非Public函数作注释。注释的详细程度应该视代码的用户群而定。
C++ 函数注释模板:
/*--------------------------------------------------------------------------- FUNCTION:
PURPOSE:
PARAMETERS:
RETURN VALUE:
EXCEPTION:
EXAMPLE CALL:
? 2015 Microsoft Corporation. All rights reserved. All-In-One Code Framework （http://1code.codeplex.com）
Page 23
REMARKS:
---------------------------------------------------------------------------*/
C# 和 VB.NET 使用 .NET 描述性 XML 文档化注释。在一般情况下，至少需要一个
C# 函数注释模板:
///
///
/// /// ///
///
/// /// VB.NET 函数注释模板: ''' ''' ''' ''' ''' ''' ''' ''' 举例, ? 2015 Microsoft Corporation. All rights reserved. All-In-One Code Framework （http://1code.codeplex.com） Page 24 /*--------------------------------------------------------------------------- FUNCTION: IsUserInAdminGroup（HANDLE hToken） PURPOSE: The function checks whether the primary access token of the process belongs to user account that is a member of the local Administrators group, even if it currently is not elevated. PARAMETERS: hToken –the handle to an access token. RETURN VALUE: Returns TRUE if the primary access token of the process belongs to user account that is a member of the local Administrators group. Returns FALSE if the token does not. EXCEPTION: If this function fails, it throws a C++ DWORD exception which contains the Win32 error code of the failure. EXAMPLE CALL: try { if （IsUserInAdminGroup（hToken）） wprintf （L\）; else wprintf （L\）; } catch （DWORD dwError） { wprintf（L\）; } ---------------------------------------------------------------------------*/ /// /// The function checks whether the primary access token of the process /// belongs to user account that is a member of the local Administrators /// group, even if it currently is not elevated. /// /// /// /// Returns true if the primary access token of the process belongs to /// user account that is a member of the local Administrators group. /// Returns false if the token does not. /// /// /// When any native Windows API call fails, the function throws a ? 2015 Microsoft Corporation. All rights reserved. All-In-One Code Framework （http://1code.codeplex.com） Page 25 /// Win32Exception with the last error code. /// 任何调用失败会带来副作用的方法或函数，都需要清楚地在注释中交代那些副作用的后果。一般而言，代码在发生错误或失败时不应该有副作用。当出现副作用时，在编写代码时应该有清楚的理由。当函数没有输出参数，或者只有一些单纯作为输出参数的情况下，无需交代理由。 2.11.5 将代码注释掉 当您用多种方法实现某些任务时，将代码注释掉便是必须的。除了第一个方法，其余实现方法都会被注释掉。使用 [-or-] 来分隔多个方法。举例, // C++ / C# sample: // Demo the first solution. DemoSolution1（）; // [-or-] // Demo the second solution. //DemoSolution2（）; ' VB.NET sample: ' Demo the first solution. DemoSolution1（）; ' [-or-] ' Demo the second solution. 'DemoSolution2（）; 2.11.6 TODO 待办注释 ?一定不要在已发布的代码示例中使用TODO 待办注释。每一个代码示例都必须完整，在代码中不能有未完成的任务。 ? 2015 Microsoft Corporation. All rights reserved. All-In-One Code Framework （http://1code.codeplex.com） Page 26 2.12 代码块 ?一定请在大量代码会因为更具结构化而获益时，使用代码块声明。通过作用域或者功能性分类，将大量代码分组，会改善代码易读性和结构。 C++ 代码块: #pragma region\... #pragma endregion C# 代码块: #region Helper Functions for XX ... #endregion VB.NET 代码块: #Region\... #EndRegion ? 2015 Microsoft Corporation. All rights reserved. All-In-One Code Framework （http://1code.codeplex.com）