苏飞论坛

标题: [C#基语法]之C#注释-一个合格程序员应该做的事 [打印本页]
作者: 站长苏飞    时间: 2018-11-26 16:47
标题: [C#基语法]之C#注释-一个合格程序员应该做的事
                                                [C#基语法]之C#注释
系列文章导航
  [C#基语法]苏飞传奇版   http://www.sufeinet.com/thread-3091-1-1.html


我对注释的理解
     我对注释的重视是从一开始学习语言就开始做的，没有注释的代码是我无论如何都无法接受的，没有注解的代码我只能说是一种不负责的做法

我们的代码想要通用，想要被更多的人优化熟悉并使用，通过注释了解是最方便最快速的方式

    做为一个程序员，无论如何都不应该不写注释。
不光要写而且要写的突出重点，一看就明白。而不是长篇大论。
下面我给大家一说一下，我平时写代码的时候习惯用到的注释方式

类文件的注释
   类一般与一个文件对应，为了不破坏它的完整性，我通常是在最上方写注释，当然这是对于一个文件一个类的情况下的写法，看代码
[C#] 纯文本查看 复制代码
/// <summary>

/// 类说明：HttpHelper类，用来实现Http访问，Post或者Get方式的，直接访问，带Cookie的，带证书的等方式，可以设置代理

/// 重要提示：请不要自行修改本类，如果因为你自己修改后将无法升级到新版本。如果确实有什么问题请到官方网站提建议，

/// 我们一定会及时修改

/// 编码日期：2011-09-20

/// 编 码 人：苏飞

/// 联系方式：361983679  

/// 官方网址：http://www.sufeinet.com/thread-3-1-1.html

/// 修改日期：2018-11-06

/// 版 本 号：1.9.9

/// </summary>

using System;

using System.Collections.Generic;

using System.Text;

using System.Net;

using System.IO;

using System.Text.RegularExpressions;

using System.IO.Compression;

using System.Security.Cryptography.X509Certificates;

using System.Net.Security;

using System.Linq;

using System.Net.Cache;



namespace SufeiUtil

{

    /// <summary>

    /// Http连接操作帮助类

    /// </summary>

    public class HttpHelper

    {

代码不全，主要看注释部分，我也就不贴完整的代码了

我一般会写以下几个要点


有了以上8点，基本上就可以满足一下类注释的基本需求了。

变量的注释
    这个就简单了，一个单行的注释就够了，当然有人可能会说一行要是写不完呢，那就写两行，但是最好一行写完，一个变量而已，说明用途就够了

[C#] 纯文本查看 复制代码
        //默认的编码

        private Encoding encoding = Encoding.Default;

        //Post数据编码

        private Encoding postencoding = Encoding.Default;

        //HttpWebRequest对象用来发起请求

        private HttpWebRequest request = null;

        //获取影响流的数据对象

        private HttpWebResponse response = null;

        //设置本地的出口ip和端口

        private IPEndPoint _IPEndPoint = null;


方法的注释
    这个先看个代码
[C#] 纯文本查看 复制代码


        /// <summary>

        /// 根据相传入的数据，得到相应页面数据

        /// </summary>

        /// <param name="item">参数类对象</param>

        public HttpResult GetHtml(HttpItem item)

        {

这里面有几点需要注意
1. 必须使用Xml格式的注释，如果我是一个团队管理者，我一定这样要求团队成员，不同意的就离职，不解释。
2. 必须对每一个参数进行说明

再来看下面这个
[C#] 纯文本查看 复制代码
   /// <summary>

        /// 获取数据的并解析的方法

        /// </summary>

        /// <param name="item"></param>

        /// <param name="result"></param>

        private void GetData(HttpItem item, HttpResult result)

        {

这是一个反面案例，这种做法是不允许的，这大部分是为了不让VS报警告的做法，正确的应该是对item,sesult参数进行说明。

大家有没有看出来上面两个例子都缺了一个方法另一个重核心的都
，？？？？
当然，也必须是返回值
比如上面第一个方法应该是这样写
[C#] 纯文本查看 复制代码
    /// <summary>

        /// 根据相传入的数据，得到相应页面数据

        /// </summary>

        /// <param name="item">参数类对象</param>

        /// <returns>返回HttpResult类型</returns>

        public HttpResult GetHtml(HttpItem item)


有时候方法上需要写个例子，这个说实话我个人不太建议写，太新手，方法的引用基本没有人不会，除非是没学过语言，一个连方法都不会引用的人，你跟他说那么多也是对牛弹琴，当然这绝不是鄙视新手，而是大家要清楚你的类使用对象，面向的是那种类型的用户，如果你是老师，你不光要写，还是手把手的教，但显然我们都不是老师，那些应该是在学习就学会的东西
如果这个都要写的话，那不如把每一个字母的音标给加上得了
太基础的可以不写。
因为随时可以百度到。

实体类的注释
   
[C#] 纯文本查看 复制代码
    /// <summary>

    /// Cookie对象

    /// </summary>

    public class CookieItem

    {

        /// <summary>

        /// 键

        /// </summary>

        public string Key { get; set; }

        /// <summary>

        /// 值

        /// </summary>

        public string Value { get; set; }

    }

比如上面一个实体类的写法，个人感觉已经够了。
类内部的方法规划region用法
   这个分类的方法有很多，我一般是根据功能，或者模块来的。
看截图
(, 下载次数: 161)