[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  
/// 官方网址：[url=http://www.sufeinet.com/thread-3-1-1.html]http://www.sufeinet.com/thread-3-1-1.html[/url]
/// 修改日期：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
    {

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

我一般会写以下几个要点

• 类说明，简明的说明一下这个类的作用和方向
• 重要提示，这里主要是写上这个类在使用过程中需要用户注意什么，也就是会影响实际输出，或者会对方法造成不良结果的地方，也可以说是Bug
• 编码日期，也就是一个类的创建时间了。
• 编码人，告诉用户 这类是自己写的
• 联系方式，方便使用者与你取得联系，毕竟用到的人不一定都认识你
• 更新地址，这个很重要，用别人的类大多是不想自己写，但随着时间的推移，总会有Bug或者不能满足的地方，这个时候用户可以根据这个地址找到最新的版本
• 修改时间，写清最后一次更新的时间
• 版本号，这个其实可有可无，如果一个产品的话这是必须的。
  

有了以上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用法

---

   这个分类的方法有很多，我一般是根据功能，或者模块来的。
看截图

还有一种方法也是我所喜欢的

这个就明确的告诉了你，里面都是干嘛的方法。
我们直接看一下第二个的代码如下

[C#] 纯文本查看 复制代码

        #region 使用 给定密钥字符串 加密/解密string
        /// <summary>
        /// 使用给定密钥字符串加密string
        /// </summary>
        /// <param name="original">原始文字</param>
        /// <param name="key">密钥</param>
        /// <param name="encoding">字符编码方案</param>
        /// <returns>密文</returns>
        public static string Encrypt(string original, string key)
        {
            byte[] buff = System.Text.Encoding.Default.GetBytes(original);
            byte[] kb = System.Text.Encoding.Default.GetBytes(key);
            return Convert.ToBase64String(Encrypt(buff, kb));
        }
        /// <summary>
        /// 使用给定密钥字符串解密string
        /// </summary>
        /// <param name="original">密文</param>
        /// <param name="key">密钥</param>
        /// <returns>明文</returns>
        public static string Decrypt(string original, string key)
        {
            return Decrypt(original, key, System.Text.Encoding.Default);
        }

        /// <summary>
        /// 使用给定密钥字符串解密string,返回指定编码方式明文
        /// </summary>
        /// <param name="encrypted">密文</param>
        /// <param name="key">密钥</param>
        /// <param name="encoding">字符编码方案</param>
        /// <returns>明文</returns>
        public static string Decrypt(string encrypted, string key, Encoding encoding)
        {
            byte[] buff = Convert.FromBase64String(encrypted);
            byte[] kb = System.Text.Encoding.Default.GetBytes(key);
            return encoding.GetString(Decrypt(buff, kb));
        }
        #endregion

总结

---

  我感觉应该是注意以下几点就行了
1. 能一句话说明白的不要写那么长
2. 能说明一下的不要偷懒
3.对于你的逻辑复杂的必须要加上注释
4.类，变量，常量，方法，属性，这些是必须要加的，没有理由。

不喜欢写注释的程序员不能算是一个合格的程序员。
也许 你会很成功，争很多钱，但绝对不是一个好程序员。

我想当一个好程序员，所以我一直在努力坚持写注释

站长苏飞

范范 发表于 2018-11-26 16:56
不过还是建议添加上基本的引用， 免得在修改优化通用代码的时候， 直接修改了方法，结果其他引用的地方出了 ...

这个其实是管理问题，你是要告诉我你们公司的管理有多混乱吗。

范范

不过还是建议添加上基本的引用， 免得在修改优化通用代码的时候， 直接修改了方法，结果其他引用的地方出了问题， 但是还没有测试到， 这就很尴尬了

范范

支持楼主，  代码的注释真的很重要， 尤其是在一个团队中， 代码注释处理好了， 其他人能很快的看懂并着手进行优化处理等

liu

强烈支持楼主ing……

惜

强烈支持楼主ing…… 收藏 学习

站长苏飞

大家有什么不同建议可以发出来交流一下。