Clean-Code: 注释

别给糟糕的代码加注释-----------------重新写吧

 

这是书中的关于注释一章的第一句话,怎么说呢,这句话个人感觉很对,但是实际上却很少这么做,

有几个原因:

  • 糟糕的代码不是自己写的,别人写的代码,还是让别人自己去维护吧,出了问题也是别人的。
  • 糟糕的代码目前可以正常工作,软件开发中有一条古老哲言:如果它能工作就不要动它,很多程序员都遵守这条准则。
  • 既然代码不能被修改,那么就只能加注释了。

上面的几个原因纯粹是自己的想法,希望你不要和我一样。

注释的好处基本上大家都知道,主要是为了方便其他人更好的查看和理解代码,下面的一些主要是乱用注释而导致的坏处:

 

可怕的注释,废话注释:

// the name

private string name;

// the version

private string version;

// the licenceName

private string licenceName;

// the version

private string info;

上面的代码注释的确多余了,并且还有剪切-粘贴错误,我想这可能是因为作者是外国人,所以对外国人来说英语是母语。但是中国的程序员大部分都用中文注释。所以上面的代码可能是这样:

// 姓名

 private string name;

 // 版本号

 private string version;

 // 许可名称

 private string licenceName;

 // 信息

 private string info;

 

虽然注释一样有些多余,不过对于英文不好的读者来说的确方便了不少。

 

下面的示例是我从某位大师的系统中抽取出来的

 

/// <summary>

/// IBaseManager

/// 通用接口部分

///

/// 总觉得自己写的程序不上档次,这些新技术也玩玩,也许做出来的东西更专业了。

/// 修改纪录

///

///     2007.11.01 版本:1.9 jjjco 改进 BUOperatorInfo 去掉这个变量,可以提高性能,提高速度,基类的又一次飞跃。

///     2007.05.23 版本:1.8 jjjco 修改完善了 对象事件触发器,完善了GetDT, ref 方法部分。

///     2007.05.20 版本:1.7 jjjco 修改完善了 对象事件触发器,完善了GetDT方法部分。

///     2007.05.19 版本:1.6 jjjco 修改完善了 DeleteExists方法部分,累了休息一下下,争取周六周日两天内完成。

///     2007.05.18 版本:1.5 jjjco 规范了一些接口的标准方法,进行了补充。

///     2007.05.17 版本:1.4 jjjco 重新调整主键的规范化,整体上又上升了一个层次了。

///     2006.02.05 版本:1.3 jjjco 重新调整主键的规范化。

///     2005.08.19 版本:1.2 jjjco 参数进行改进

///     2004.07.23 版本:1.1 jjjco 增加了接口ClearPropertyGetFromDS 的定义。

///     2004.07.21 版本:1.0 jjjco 提炼了最基础的方法部分、觉得这些是很有必要的方法。

///

/// 版本:1.8

///

/// <author>

///     <name>jjjco</name>

///     <date>2007.05.23</date>

/// </author>

/// </summary>

public interface IBaseManager

{

    xxxxxx

}

 

这段注释有几个问题:

  1. 喃喃自语,
  2. 修改记录在有源代码管理的情况下,完全多余,不过鉴于最早的版本是 2004.07.21, 这一点,修改记录问题也不大。
  3. 注释中版本的不一致,最新的版本是 2007.11.01 的版本 1.9 . 但是下面显示的版本是 1.8. 版本不一致的原因是作者忘记了,包括下面的 <date> 2007.05.23 </date>

 

#region 注释

msdn  解释:

#region 使您可以在使用 Visual Studio 代码编辑器的 大纲显示功能时指定可展开或折叠的代码块。 在较长的代码文件中,能够折叠或隐藏一个或多个区域会十分便利,这样,您可将精力集中于当前处理的文件部分。

 

#region MyClass definition

public class MyClass

{

    static void Main()

    {

    }

}

#endregion

 

效果如下:

clip_image002

记得以前我刚接触#region的时候,习惯性的写上了这样的代码:

Clean-Code: 注释_第1张图片

 

对于经常使用#region的同学肯定知道上面的代码的问题。#region 后面是不需要加 “//” 的。

 

大师不愧是大师,另一个经典的注释是让你忘记不了他是如何使用#region的。

Clean-Code: 注释_第2张图片

当我看到DbLogic的时候,我彻底崩溃了。

不过在批评别人的同时,我还是要说下大师的优点:

 

  1. 代码结构清晰
  2. 命名相对来说还算规范
  3. 注释非常详细,虽然像上面的注释不在少数,但是不可否认的是注释非常详细,比如:

Clean-Code: 注释_第3张图片

作者: LoveJenny 发表于 2011-09-16 06:14 原文链接

评论: 5 查看评论 发表评论

最新新闻:
· 开发者应关注的Visual Studio 11新特性(2011-09-16 14:11)
· 诺基亚中国裁员追踪:被裁员工对新方案仍不满(2011-09-16 13:50)
· 消息称淘宝商城下周将推出开放平台 针对独立B2C(2011-09-16 13:46)
· 盛大创新院发布光速搜索工具 将不涉足全网搜索(2011-09-16 13:31)
· 中电信部分省市已接到iPhone 5销售准备通知(2011-09-16 13:08)

编辑推荐:微软Build大会Windows 8新闻汇总

网站导航:博客园首页  我的园子  新闻  闪存  小组  博问  知识库

你可能感兴趣的:(code,clean)