• 设为首页
  • 点击收藏
  • 手机版
    手机扫一扫访问
    迪恩网络手机版
  • 关注官方公众号
    微信扫一扫关注
    公众号

C#注释——爱你不是两三天

原作者: [db:作者] 来自: [db:来源] 收藏 邀请
说到注释这个东东,我不得不说:爱你不是两三天,每天却想你很多遍、、、原来梁静茹同学这首歌不全然是情歌啊~
 
一句注释也没有的一大片的代码有木有
看着那些无名者写的神秘代码,有没有骂一句,你妹的、、、
几千行的代码里边全是注释掉的东东有木有
为什么你写的类库没人用啊,因为我看不懂,你可以说我是小白,但是其他人貌似也一样
、、、、、、
 
没有注释的日子里,程序员只能感叹一声:悲惨世界
那有了注释呢,情况貌似是这样的:自从用上了好的注释,我写代码也不头疼了,腰板也值了,一口气写到5千行,不费劲,你值得拥有!
 
那C#里边也就三种注释,仅此而已,用好了你好我好团队好,那就吐糟一下他们吧!
 
A、单行注释
这个仅仅用于注释单行的代码,以"//" 开始,可以从一行的任何处开始,还有快捷键可用哦“Ctrl +K+C”
string distinctstring = string.Empty; // 根据此字段是否为空来判断是否需要统计所查数据中的酒店数量

也有些人愣是侮辱我等程序猿的智商

if (a > 0)         //如果a大于0
 console.write(a);//输出变量a

 B、多行注释

以“/*”开始,以“*/”结束,这两个标记中间的东东全是注释

/********************************
     * 版    本:xxx       
     * 类 名 称:xxx       
     * 机器名称:xxx       
     * 命名空间:xxx       
     * 文 件 名 :xxx       
     * 创建时间:xxx       
     * 作   者:xxx
     * 说   明:xxx
     * 修改时间:xxx
     * 修 改 人:xxx

*********************************/

C、xml注释

你只需要在vs中按“///”,它就会自动添加,你再填入相关的东东即可,这个形式的注释还可以生成XML注释文档的哦

/// <summary>
        /// 返回酒店运营数据
        /// </summary>
        /// <param name="strSql">sql执行语句</param>
        /// <returns>返回datatable数据</returns>
        public DataTable GetHotelOperatorsData(string strSql)
        {
            DataSet ds = SqlHelper.ExecuteDataset(SqlHelper.CrsString, CommandType.Text, strSql);
            var myCharData = new DataTable();
            if (ds!=null)
            {
                myCharData = ds.Tables[0];
            }
            return myCharData;
        }

至于生成xml文档,就是在标注完成后通过项目的属性面板中的生成选项导出xml文件

勾选xml文档文件,F6生成解决方案后,即可在输出路径下找到对应文件

总结:

1、在程序中可以临时注释掉某些代码达到调试的目的

2、不用的注释要删除掉,要不然影响性能的

3、要分类注释,比如类的注释,方法的注释,整个文件头的注释等

4、尽量让你的注释风格统一,同时能够美观一点

5、写代码的时候就添加,不要指望以后再弄

6、保持注释是最新版本

7、团队开发代码时,使用todo注释,说明此处代码还没有开发完成

 public GetData()
     {
         //
         // TODO: Add Logic here
         //
     }

8、每个文件头必须注释,保持这个习惯

// <copyright file="文件名.cs" company="HP">
//  Copyright (c) WW. All rights reserved.
// </copyright>
// <author>×××</author>
// <date> yyyy-mm-dd </date>
// <summary>文件功能描述</summary>
// <modify>
//      修改人:×××
//      修改时间:yyyy-mm-dd
//      修改描述:×××
//      版本:1.0
//</modify>

9、类、接口等注释

/// <summary>
    /// 类功能的说明
    /// </summary>
    /// <see cref=""></see>
    /// <remarks>
    /// 创建人:WANG
    /// 创建日期:yyyy-mm-dd
    /// 修改人:LI
    /// 修改日期:yyyy-mm-dd
    /// 修改备注:无
    /// 版本:1.0
    /// </remarks>
    public class Student : Person
    {
//code }

10、方法事件等注释

        /// <summary>
        /// 根据员工编号获得员工信息
        /// </summary>
        /// <param name="employeeId">员工编号</param>
        /// <exception cref="System.Exception">系统异常</exception>
        /// <returns>员工姓名</returns>
        /// <remarks>
        /// 创建人:WANG
        /// 创建日期:yyyy-mm-dd
        /// 修改人:LI
        /// 修改日期:yyyy-mm-dd
        /// 修改备注:无
        /// 版本:1.1
        /// </remarks>
        public string GetEmployeeNameById(int employeeId)
        {
            try
            {
                return "ddd";
            }
            catch (System.Exception)
            {
                throw;
            }
}

 

附件:注释标签,你也可以自定义标签,之后会在生成的xml注释文档里有所体现

 

标签

用法

作用

<c>

c>text</c>

 

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

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

<para>

<para>content</para>

content段落文本。

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

<param>

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

name 为方法参数名。将此名称用单引号括起来 (' ')

应当用于方法声明的注释中,以描述方法的一个参数。

<paramref>

 

<paramref name="name"/>

name

要引用的参数名。将此名称用双引号括起来 (" ")

<paramref> 标记为您提供了一种指示词为参数的方法。可以处理 XML 文件,从而用某种独特的方法格式化该参数。

<see>

<see cref="member"/>

 

cref = "member" 对可以通过当前编译环境进行调用的成员或字段的引用。编译器检查到给定代码元素存在后,将 member 传递给输出 XML 中的元素名。必须将 member 括在双引号 (" ") 中。

使您得以从文本内指定链接。使用 <seealso> 指示希望在请参阅一节中出现的文本。

<seealso>

<seealso cref="member"/>

cref = "member" 对可以通过当前编译环境进行调用的成员或字段的引用。编译器检查到给定代码元素存在后,将 member 传递给输出 XML 中的元素名。必须将 member 括在双引号 (" ")

使您得以指定希望在请参阅一节中出现的文本。使用 <see> 从文本

<example>

<example>description</example>

description

代码示例的说明。

使用 <example> 标记可以指定使用方法或其他库成员的示例。一般情况下,这将涉及到 <code> 标记的使用。

<code>

<code>content</code>

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

 

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

<summary>

<summary>description</summary>

此处description 为对象的摘要。

应当用于描述类型成员。使用 <remarks> 以提供有关类型本身的信息。

<exception>

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

cref = "member" 对可从当前编译环境中获取的异常的引用。编译器检查到给定异常存在后,将 member 转换为输出 XML 中的规范化元素名。必须将 member 括在双引号 (" ") 中。

description 说明。

<exception> 标记使您可以指定类能够引发的异常。

<include>

<include file='filename' path='tagpath[@name="id"]' />

filename 包含文档的文件名。该文件名可用路径加以限定。将 filename 括在单引号中 (' ')

Tagpath:filename 中指向标记名的标记路径。将此路径括在单引号中 (' ')

name 注释前边的标记中的名称说明符;名称具有一个 id

id

位于注释之前的标记的 id。将此 id 括在双引号中 (" ")

<include> 标记使您得以引用描述源代码中类型和成员的另一文件中的注释。这是除了将文档注释直接置于源代码文件中之外的另一种可选方法。

<include> 标记使用 XML XPath 语法。有关自定义 <include> 使用的方法,请参阅 XPath 文档。

<list>

<list type="bullet" | "number" | "table">

   <listheader>

      <term>term</term>

      <description>description</description>

   </listheader>

   <item>

      <term>term</term>

      <description>description</description>

   </item>

</list>

 

term  定义的项,该项将在 text 中定义。

description  目符号列表或编号列表中的项或者 term 的定义。

<listheader> 块用于定义表或定义列表中的标题行。定义表时,只需为标题中的项提供一个项。

列表中的每一项用 <item> 块指定。创建定义列表时,既需要指定 term 也需要指定 text。但是,对于表、项目符号列表或编号列表,只需为 text 提供一个项。

列表或表所拥有的 <item> 块数可以根据需要而定。

<permission>

<permission cref="member">description</permission>

 

cref = "member" 对可以通过当前编译环境进行调用的成员或字段的引用。编译器检查到给定代码元素存在后,将 member 转换为输出 XML 中的规范化元素名。必须将 member 括在双引号 (" ") 中。

description  成员的访问的说明。

<permission> 标记使您得以将成员的访问记入文档。System.Security.PermissionSet 使您得以指定对成员的访问。

<remarks>

<remarks>description</remarks>

description 成员的说明。

<remarks> 标记是可以指定有关类或其他类型的概述信息的位置。<summary> 是可以描述该类型的成员的位置。

<returns>

<returns>description</returns>

description 返回值的说明。

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

<value>

<value>property-description</value>

property-description 属性的说明。

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

 

标签

用法

作用

<c>

c>text</c>

 

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

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

<para>

<para>content</para>

content段落文本。

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

<param>

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

name 为方法参数名。将此名称用单引号括起来 (' ')

应当用于方法声明的注释中,以描述方法的一个参数。

<paramref>

 

<paramref name="name"/>

name

要引用的参数名。将此名称用双引号括起来 (" ")

<paramref> 标记为您提供了一种指示词为参数的方法。可以处理 XML 文件,从而用某种独特的方法格式化该参数。

<see>

<see cref="member"/>

 

cref = "member" 对可以通过当前编译环境进行调用的成员或字段的引用。编译器检查到给定代码元素存在后,将 member 传递给输出 XML 中的元素名。必须将 member 括在双引号 (" ") 中。

使您得以从文本内指定链接。使用 <seealso> 指示希望在请参阅一节中出现的文本。

<seealso>

<seealso cref="member"/>

cref = "member" 对可以通过当前编译环境进行调用的成员或字段的引用。编译器检查到给定代码元素存在后,将 member 传递给输出 XML 中的元素名。必须将 member 括在双引号 (" ")

使您得以指定希望在请参阅一节中出现的文本。使用 <see> 从文本

<example>

<example>description</example>

description

代码示例的说明。

使用 <example> 标记可以指定使用方法或其他库成员的示例。一般情况下,这将涉及到 <code> 标记的使用。

<code>

<code>content</code>

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

 

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

<summary>

<summary>description</summary>

此处description 为对象的摘要。

应当用于描述类型成员。使用 <remarks> 以提供有关类型本身的信息。

<exception>

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

cref = "member" 对可从当前编译环境中获取的异常的引用。编译器检查到给定异常存在后,将 member 转换为输出 XML 中的规范化元素名。必须将 member 括在双引号 (" ") 中。

description 说明。

<exception> 标记使您可以指定类能够引发的异常。

<include>

<include file='filename' path='tagpath[@name="id"]' />

filename 包含文档的文件名。该文件名可用路径加以限定。将 filename 括在单引号中 (' ')

Tagpath:filename 中指向标记名的标记路径。将此路径括在单引号中 (' ')

name 注释前边的标记中的名称说明符;名称具有一个 id

id

位于注释之前的标记的 id。将此 id 括在双引号中 (" ")

<include> 标记使您得以引用描述源代码中类型和成员的另一文件中的注释。这是除了将文档注释直接置于源代码文件中之外的另一种可选方法。

<include> 标记使用 XML XPath 语法。有关自定义 <include> 使用的方法,请参阅 XPath 文档。

<list>

<list type="bullet" | "number" | "table">

   <listheader>

      <term>term</term>

      <description>description</description>

   </listheader>

   <item>

      <term>term</term>

      <description>description</description>

   </item>

</list>

 

term  定义的项,该项将在 text 中定义。

description  目符号列表或编号列表中的项或者 term 的定义。

<listheader> 块用于定义表或定义列表中的标题行。定义表时,只需为标题中的项提供一个项。

列表中的每一项用 <item> 块指定。创建定义列表时,既需要指定 term 也需要指定 text。但是,对于表、项目符号列表或编号列表,只需为 text 提供一个项。

列表或表所拥有的 <item> 块数可以根据需要而定。

<permission>

<permission cref="member">description</permission>

 

cref = "member" 对可以通过当前编译环境进行调用的成员或字段的引用。编译器检查到给定代码元素存在后,将 member 转换为输出 XML 中的规范化元素名。必须将 member 括在双引号 (" ") 中。

description  成员的访问的说明。

<permission> 标记使您得以将成员的访问记入文档。System.Security.PermissionSet 使您得以指定对成员的访问。

<remarks>

<remarks>description</remarks>

description 成员的说明。

<remarks> 标记是可以指定有关类或其他类型的概述信息的位置。<summary> 是可以描述该类型的成员的位置。

<returns>

<returns>description</returns>

description 返回值的说明。

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

<value>

<value>property-description</value>

property-description 属性的说明。

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


鲜花

握手

雷人

路过

鸡蛋
该文章已有0人参与评论

请发表评论

全部评论

专题导读
上一篇:
Effective C++ 总结笔记(五)发布时间:2022-07-13
下一篇:
初尝C# 连接本地数据存储 SQLite发布时间:2022-07-13
热门推荐
阅读排行榜

扫描微信二维码

查看手机版网站

随时了解更新最新资讯

139-2527-9053

在线客服(服务时间 9:00~18:00)

在线QQ客服
地址:深圳市南山区西丽大学城创智工业园
电邮:jeky_zhao#qq.com
移动电话:139-2527-9053

Powered by 互联科技 X3.4© 2001-2213 极客世界.|Sitemap