Clean-Code: 注释

标签: clean code | 发表时间:2011-09-15 22:14 | 作者:LoveJenny We_Get
分享到:
出处:http://www.cnblogs.com/

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

 

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

有几个原因:

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

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

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

 

可怕的注释,废话注释:

// 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的时候,习惯性的写上了这样的代码:

image

 

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

 

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

clip_image002

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

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

 

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

clip_image002

作者: 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新闻汇总

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

相关 [clean code] 推荐:

Clean-Code: 注释

- We_Get - 博客园-首页原创精华区
别给糟糕的代码加注释-----------------重新写吧. 这是书中的关于注释一章的第一句话,怎么说呢,这句话个人感觉很对,但是实际上却很少这么做,. 糟糕的代码不是自己写的,别人写的代码,还是让别人自己去维护吧,出了问题也是别人的. 糟糕的代码目前可以正常工作,软件开发中有一条古老哲言:如果它能工作就不要动它,很多程序员都遵守这条准则.

什么是整洁的代码(Clean Code)?

- - 博客 - 伯乐在线
英文原文: What Is Clean Code?,编译: iteye – wangguo. 什么样的代码才是真正好的、整洁的代码. Bjarne Stroustrup,C++之父:. ● 逻辑应该是清晰的,bug难以隐藏;. ●错误处理完全根据一个明确的策略;. ●性能接近最佳化,避免代码混乱和无原则的优化;.

聊聊Code Review

- - 梦想风暴
hopesfish评论《 那一点的调用》时,问了一个关于Code Review的问题:. 想请教一下,TW的筒子是如何做code reivew或者鼓励客户做code review的. 我在翻阅博主的帖子的时候,似乎对这块没有特别强调,而是更多偏重于TDD,我觉得TDD的问题是一碰到没有责任心的程序猿,就很容易流于形式了.

Java Code Review清单

- - ImportNew
使用可以表达实际意图(Intention-Revealing)的名称. DRY(Don’t Repeat Yourself)原则,(拒绝重复). 用代码来解释自己的做法(译者注:即代码注释). *参考自: http://techbus.safaribooksonline.com/book/software-engineering-and-development/agile-development/9780136083238.

我的code review规则

- vento - 我的宝贝孙秀楠 ﹣C++, Lua, 大连,程序员
1) 是否有语法错误,编译错误,编译警告. 做法:下载最新代码,将编译警告级别提升到最高,检查output信息. 2)是否符合需求,完成requirement文档要求的内容,不能多,也不能少. 注意:即使发现有问题代码,如果与需求关联不大,不要涉及. 应该让每次enhancement和bug fix最简洁,牵涉范围最小,影响到组件最少.

Google Code Jam Japan開催

- Adam - スラッシュドット・ジャパン
あるAnonymous Coward 曰く、Googleによって毎年開催されているプログラミングコンテストGoogle Code Jamですが、今年は初めて日本人向けの日本語でのコンテストGoogle Code Jam Japanが開催されるようです(Google Japan Blog). 予選は10月1日にオンラインで開催され、予選開催中にも参加登録を受け付けるとのこと(スケジュール).

Code Review那些事儿

- - 非技术 - ITeye博客
       曾经有一段 垃圾代码放在我的面前,我没有拒绝,等我真正开始接手的时候我才后悔莫及,程序员最痛苦的事莫过于此. ---------改编于周星星的经典台词.       虽然有点夸张,但编码界确实大大存在这种情况,每当接手别人的代码,都有一种想重新写一遍的感觉,等到别人再来接手你的代码时,同样的感觉.

社交网络上的 Riot Clean-up 运动已经展开

- TT Jobs - 爱范儿 · Beats of Bits
在这次骚乱中,英国各媒体对社交网络的看法大相径庭,卫报认为社交网络发挥了积极作用,而太阳报则认为 Twitter 促进了骚乱. 但是在 Twitter 和 Facebook 上展开的 Riot Clean-up 行动则再次证明:社交网络只是一个工具,它可以用于破坏,而且可以用于建设. 套用一句老话:我们是否应该把洗脚水和孩子一起倒掉.

Google 7500 万美元投资太阳能基金 Clean Power Finance

- mike - 谷奥——探寻谷歌的奥秘
Google一直对新能源情有独钟,他们之前也曾以2亿8000万美元投资过可安装在家庭房屋上的太阳能公司SolarCity,今天他们再次投资太阳能事业──太阳能创业基金Clean Power Finance,Clean Power Finance将利用这笔投资推进第三方的屋顶太阳能装置工程. Google说他们喜欢这种商业模式,因为他们的投资可用于让更多美国人安装并使用太阳能,他们希望自己能帮助超过一万户家庭使用太阳能这种清洁能源.

Clean – 桌面清洁工 [Mac] | 小众软件 > Mac

- Chinaxingwei - 小众软件
Clean 做的事情很简单,无非就是每天清空一次桌面,把桌面所有文件扫入以当天日期命名的文件夹. 搞乱桌面不用收拾,拉屎不用自己擦屁股,这不是人类的梦想么. 下载: MAS | 来自小众软件. ©2011 Thruth for 小众软件 | 原文链接 | 1 留言 | 加入我们 | 投稿 | 订阅指南.