KV58 Note 04 有关编程细节 PART1

1.关于工程内头文件包含问题

<include.h>编写时,头文件包含顺序应有主次,
越底层的库写在越前面,使用了底层库的库应在后,否则会发生编译时编译器认为某些底层库没有被声明的情况。且注意包含结构应该是有向无环的,从根展开,因此直接从'include.h"开始展开,而不是进行回溯
否则会出现“在涉及到.h内容之前就已经展开到了.h被调用的内容”而报错那个内容不存在,停止编译

2.XML风格注释

例:

/// <summary>
///     根据用户Id得到用户名.
///     <para>
///         此处添加第二段Summary信息,在MSDN中很少使用.所以不推荐使用.
///     </para>  
/// </summary>
/// <remarks>
///     如果没有找到用户则返回null.<br/>
///     <paramref name="userId"/> 参数为正整数.<br/>
///     用户Id模型属性定义参见<see cref="UserInfo.UserId"/><br/>
///     相关方法:<seealso cref="UserBL.GetUserId"/>
/// </remarks>
/// <param name="userId">用户Id</param>
/// <returns>用户真实姓名</returns>
/// <example>
///     返回用户id为100的用户真实姓名:
///     <code>
///         private string userName = string.Empty;
///         userName = UserBL.GetUserName(100);
///     </code>
///     返回的用户名可能为null,使用时要先判断:<br/>
///     <c>if(userName!=null){...}</c>
/// </example>
/// <exception cref="System.ApplicationException">
///     如果用户Id小于0则抛出此异常
/// </exception>
public static string GetUserName(long userId);

<summary>

<summary> 标记应当用于描述类型或类型成员。使用 ///<remarks> 添加针对某个类型说明的补充信息。
<summary> 标记的文本是唯一有关 IntelliSense 中的类型的信息源,它也显示在 对象浏览器 中。

///<summary>
///Description
///</summary>

description:对象的摘要。

<remarks>

使用 <remarks>标记添加有关类型的信息,以此补充用 <summary> 指定的信息。此信息显示在对象浏览器中。

///<remarks>
///Description
///</remarks>

description:成员的说明。

<param>

<param> 标记应当用于方法声明的注释中,以描述方法的一个参数。
有关 <param> 标记的文本将显示在 IntelliSense、对象浏览器和代码注释 Web 报表中。

///<paramname='name'>
///description
///</param>

name:方法参数名。将此名称用双引号括起来 (" ")。
description:参数说明。

<returns>

<returns> 标记应当用于方法声明的注释,以描述返回值。

///<returns>
///Description
///</returns>

description:返回值的说明。

<value>

<value> 标记使您得以描述属性所代表的值。请注意,当在 Visual Studio .NET开发环境中通过代码向导添加属性时,它将会为新属性添加 <summary> 标记。然后,应该手动添加 <value> 标记以描述该属性所表示的值。

///<value>
///property-description
///</value>

property-description:属性的说明

<example>

使用 <example> 标记可以指定使用方法或其他库成员的示例。这通常涉及使用 <code> 标记。

///<example>
///Description
///</example>

description: 代码示例的说明。

<c>

<c> 标记为您提供了一种将说明中的文本标记为代码的方法。使用 <code> 将多行指示为代码。

///<c>
///Text
///</c>

text :希望将其指示为代码的文本。

<code>

使用 <code> 标记将多行指示为代码。使用<c>指示应将说明中的文本标记为代码。

///<code>
///Content
///</code>

content:希望将其标记为代码的文本。

<exception>

<exception> 标记使您可以指定哪些异常可被引发。此标记可用在方法、属性、事件和索引器的定义中。

///<exception cref="member">
///Description
///</exception>

cref:对可从当前编译环境中获取的异常的引用。编译器检查到给定异常存在后,将 member 转换为输出 XML 中的规范化元素名。必须将 member 括在双引号 (" ") 中。有关如何创建对泛型类型的 cref 引用的更多信息,请参见 <see>
description:异常的说明。

<see> <seealso>

<see> 标记使您得以从文本内指定链接。
使用 <seealso> 指示文本应该放在“另请参见”节中。

<see cref="member"/>

cref:对可以通过当前编译环境进行调用的成员或字段的引用。编译器检查给定的代码元素是否存在,并将 member 传递给输出 XML 中的元素名称。应将 member 放在双引号 (" ") 中。

<para>

<para> 标记用于诸如<summary>,<remarks> 或 <returns> 等标记内,使您得以将结构添加到文本中。

///<para>
///content
///</para>

content:段落文本。

3.javadoc 和 javadoc注释规范

@author 作者

作者标识

@version 版本号

版本号

@param 参数名 描述

方法的入参名及描述信息,如入参有特别要求,可在此注释

@return 描述

对函数返回值的注释

@deprecated 过期文本

标识随着程序版本的提升,当前API已经过期,仅为了保证兼容性依然存在,以此告之开发者不应再用这个API

@throws 异常类名

构造函数或方法所会抛出的异常

@exception 异常类名

同@throws

@see 引用

查看相关内容,如类、方法、变量等

@since 描述文本

API在什么程序的什么版本后开发支持

链接到某个特定的成员对应的文档中

{@value}

当对常量进行注释时,如果想将其值包含在文档中,则通过该标签来引用常量的值。