- 浏览: 1031214 次
- 性别:
- 来自: 郑州
文章分类
- 全部博客 (605)
- 数据挖掘 (22)
- spring (40)
- 工具使用 (39)
- java (137)
- JavaScript (40)
- webwork (12)
- web (120)
- 资源 (7)
- SSH (5)
- oracle (20)
- J2ME (1)
- 环境配置 (37)
- 项目管理 (29)
- mysql (14)
- struts (4)
- 项目总结 (27)
- ibatis学习 (33)
- 学习计划 (2)
- 缓存 (7)
- 重构 (3)
- Android (1)
- jquery (12)
- UML (3)
- 用户体验 (4)
- 习惯 (7)
- sakai (1)
- urlrewrite (4)
- rss (5)
- C plus plus (5)
- 算法 (5)
- 海量数据处理 (7)
- office(word、excel) (1)
- 面试题 (3)
- solr (8)
- 大数据 (2)
最新评论
-
hujin19861102:
截图看不见,最后一个webwrok的配置看不见
Ext+Webwork+Json 实现分页表格查询效果 -
蜗牛笔:
弱弱的问一句,要是分出来的词在词典中没有,那么两部分的pos- ...
ICTCLAS 中科院分词系统 -
weipeng1986:
授人予鱼不如授人予鱼,我想问你的是你是怎么总结的。比如第四种情 ...
JAVA中字符串连接效率的测试 -
xiaoqiang2008:
执行两次的原因是什么,好像楼主没弄清楚啊!是不是在web.xm ...
关于Spring中用quartz定时器在定时到达时同时执行两次的问题 -
Kent_Mu:
...
ibatis-dynamic的用法
原文: http://coolshell.cn/?p=2746
在酷壳,有很多文章都提到了代码注释,如:《十条不错的编程观点》、《优质代码的十诫》、《整洁代码的4个提示》、《惹恼程序员的十件事》等等。今天,某国外的程序员在这里列举五种应该避免的程序注释,我觉得比较有道理,但我觉得有少数几个观点也并不绝对。所以,我把原文的这五种应该避免的程序注释罗列在下面,并放上原作者和我的个人观点作为比较。希望对大家有用。
一、自恋型注释
(注:原文为Proud,我觉得“自恋”更好一点)
public class Program
{
static void Main(string[] args)
{
string message = "Hello World!"; // 07/24/2010 Bob
Console.WriteLine(message); // 07/24/2010 Bob
message = "I am so proud of this code!"; // 07/24/2010 Bob
Console.WriteLine(message); // 07/24/2010 Bob
}
}原文:这样的程序员对于自己的代码改动非常骄傲和自恋,所以,他觉得需在在这些自己的代码上标上自己的名字。其实,一个版本控制工具(如:CVS或Subversion)可以完整地记录下所有的关于代码的改动的和作者相关的一切信息,只不过不是那么明显罢了。
陈皓:我同意原文的观点。在我的团队里也有这样的事情发生。有段时间我认真思考过这样的事情,是否应该把这样的事情在代码中铲除出去。后来,我觉得,允许这样的行为并不一定是坏事,因为两点:
调动程序员下属的积极性可能更为重要。即然,这种方式可以让程序员有骄傲的感觉,能在写代码中找到成就感,为什么要阻止呢?又不是什么大问题。
调动程序员的负责任的态度。程序员敢把自己的名字放在代码里,说明他对这些代码的信心,是想向大家展示其才能。所以,他当然知道,如果这段他加入的代码有问题的话,他的声誉必然受到损失,所以,他敢这么干,也就表明他敢于对自己的代码全面的负责。这不正是我们所需要的?!
所以,基于上述考虑,我个人认为,从代码的技术角度上来说,这样的注释很不好。但从团队的激励和管理上来说,这样的方式可能也挺好的。所以,我并不阻止也不鼓励这样的注释。关键在于其是否能有更好的结果。
二、废弃代码的注释
public class Program
{
static void Main(string[] args)
{
/* This block of code is no longer needed
* because we found out that Y2K was a hoax
* and our systems did not roll over to 1/1/1900 */
//DateTime today = DateTime.Today;
//if (today == new DateTime(1900, 1, 1))
//{
// today = today.AddYears(100);
// string message = "The date has been fixed for Y2K.";
// Console.WriteLine(message);
//}
}
}原文:如果某段代码不再使用了,那就应该直接删除。我们不应该使用注释来标准废弃的代码。同样,我们有版本控制工具来管理我们的源代码,在版本控制工具里,是不可能有代码能被真正的物理删除的。所以,你总是可以从以前的版本上找回你的代码的。
陈皓:我非常同意这样的观点。只要你是废弃的,就应该是删除,而不是注释掉。注释并不是用来删除代码的。也许你会争论到,在迭代开发中,你觉得被注释的代码很有可能在未来会被使用,但现在因为种种问题暂时用不到,所以,你先注释着,然后等到某一天再enable它。所以你注释掉一些未来会有的程序。在这样的情况,你可以注释掉这段代码,但你要明白,这段代码不是“废弃”的,而是“临时”不用的。所以,我在这里提醒你,请不要教条式地在你的程序源码中杜绝这样的注释形式,是否“废弃”是其关键。
三、明显的注释
public class Program
{
static void Main(string[] args)
{
/* This is a for loop that prints the
* words "I Rule!" to the console screen
* 1 million times, each on its own line. It
* accomplishes this by starting at 0 and
* incrementing by 1. If the value of the
* counter equals 1 million the for loop
* stops executing.*/
for (int i = 0; i < 1000000; i++)
{
Console.WriteLine("I Rule!");
}
}
}原文:看看上面的例子,代码比注释还容易读。是的,大家都是程序员,对于一些简单的,显而易见的程序逻辑,不需要注释的。而且,你不需要在你的注释中教别人怎么编程,你这是在浪费时间去解释那些显而易见的东西。你应该用注释去解释你的代码功能,原因,想法,而不是代码本身。
陈皓:非常同意。最理解的情况是你的代码写得直接易读,代码本身就是自解释的,根本不需要注释。这是最高境界。注释应该说明下面的代码主要完成什么样的功能,为什么需要他,其主要算法怎么设计的,等等。而不是解释代码是怎么工作的。这点很多新手程序员都做得不够好。别外,我需要指出的是,代码注释不宜过多,如果太多的话,你应该去写文档,而不是写注释了。
四、故事型注释
public class Program
{
static void Main(string[] args)
{
/* I discussed with Jim from Sales over coffee
* at the Starbucks on main street one day and he
* told me that Sales Reps receive commission
* based upon the following structure.
* Friday: 25%
* Wednesday: 15%
* All Other Days: 5%
* Did I mention that I ordered the Caramel Latte with
* a double shot of Espresso?
*/
double price = 5.00;
double commissionRate;
double commission;
if (DateTime.Today.DayOfWeek == DayOfWeek.Friday)
{
commissionRate = .25;
}
else if (DateTime.Today.DayOfWeek == DayOfWeek.Wednesday)
{
commissionRate = .15;
}
else
{
commissionRate = .05;
}
commission = price * commissionRate;
}
}原文:如果你不得不在你的代码注释中提及需求,那也不应该提及人名。在上面的示例中,好像程序想要告诉其它程序员,下面那些代码的典故来自销售部的Jim,如果有不懂的,你可以去问他。其实,这根本没有必要在注释中提到一些和代码不相干的事。
陈皓:太同意了。这里仅仅是代码,不要在代码中掺入别的和代码不相干的事。这里你也许会有以下的争辩:
有时候,那些所谓的“高手”逼着我这么干,所以,我要把他的名字放在这里让所有人看看他有多SB。
有时候,我对需求并不了解,我们应该放一个联系人在在这里,以便你可以去询问之。
对于第一点,我觉得这是一种情绪化。如果你的上级提出一些很SB的想法,我觉得你应该做的是努力去和他沟通,说明你的想法。如果这样都不行的话,你应该让你的经理或是那个高手很正式地把他的想法和方案写在文档里或是电子邮件里,然后,你去执行。这样,当出现问题的时候,你可以用他的文档和邮件作为你的免责证据,而不是在代码里干这些事。
对于第二点,这些需求的联系人应该是在需求文档中,如果有人有一天给你提了一个需求,你应该把其写在你的需求文档中,而不是你的代码里。要学会使用流程来管理你的工作,而不是用注释。
最后,关于故事型的注释,我需要指出也有例外的情况,我们团队中有人写注释喜欢在注释或文档里写一些名人名言(如 22条经典的编程引言,编程引言补充,Linus Torvalds 语录 Top 10 ),甚至写一些小笑话,幽默的短句。我并不鼓励这么做,但如果这样有利于培养团队文化,有利于让大家对工作更感兴趣,有利于大家在一种轻松愉快的环境下读/写代码,那不也是挺好的事吗?
另外,做为一个管理者,有时候我们应该去看看程序员的注释,因为那里面可能会有程序员最直实的想法和情绪(程序员嘴最脏??)。了解了他们的想法有利于你的管理。
五、“TODO”注释
public class Program
{
static void Main(string[] args)
{
//TODO: I need to fix this someday – 07/24/1995 Bob
/* I know this error message is hard coded and
* I am relying on a Contains function, but
* someday I will make this code print a
* meaningful error message and exit gracefully.
* I just don’t have the time right now.
*/
string message = "An error has occurred";
if(message.Contains("error"))
{
throw new Exception(message);
}
}
}原文:当你在初始化一个项目的时候,TODO注释是非常有用的。但是,如果这样的注释在你的产品源码中出现了N多年,那就有问题了。如果有BUG要被fix,那就Fix吧,没有必要整一个TODO。
陈皓:是的,TODO是一个好的标志仅当存在于还未release的项目中,如果你的软件产品都release了,你的代码里还有TODO,这个就不对了。也许你会争辩说,那是你下一个版本要干的事。OK,那你应该使用项目管理,或是需求管理来管理你下一个版本要干的事,而不是使用代码注释。通常,在项目release的前夕,你应该走查一下你代码中的TODO标志,并且做出决定,是马上做,还是以后做。如果是以后做,那么,你应该使用项目管理或需求管理的流程。
上述是你应该避免使用的注释,以及我个人的一些观点,也欢迎你留下你的观点!
本文来自CSDN博客,转载请标明出处:http://blog.csdn.net/haoel/archive/2010/08/02/5782907.aspx
发表评论
-
正确地kill java进程
2012-03-06 11:36 1321在linux/unix下,你会怎么中止一个java进程? ... -
TOMCAT中可以限制某些IP访问
2012-03-06 11:32 1072找到context区域,如 <context path= ... -
eclipse下svn的分支与合并操作
2011-08-19 14:50 1508原创作品,允许转载,转载时请务必以超链接形式标明文章 原始出处 ... -
eclipse下SVN subclipse插件
2011-08-19 14:42 1185本文目的 让未使用过 ... -
程序员应知——团队精神
2010-08-10 23:16 929大家都知道,现在的软 ... -
程序员应知:你有几种武器
2010-08-08 23:12 948程序员应知:你有几种武器? http://news.cs ... -
这领导当的,你该怎么办?
2010-08-08 23:10 980公司有一个部门很不 ... -
没人把程序员当回事儿
2010-07-22 00:48 893没人把程序员当回事儿 ... -
IT外企那点儿事(7):做一个优秀的基层【转】
2010-05-23 22:09 789千里之行,始于足下 ... -
优秀的员工究竟应该是你的棋子, 还是应该成为和你同进退的合作伙伴?
2010-05-17 23:04 819优秀的员工究竟应该是你的棋子, 还是应该成为和你同进退的合作伙 ... -
如何能调动团队的积极性[转]
2010-05-16 23:51 1274原文: http://jackyrong.itey ... -
曹重英:技术人员也要打造人脉竞争力[转]
2010-05-11 23:58 861技术人员是最不擅长交际的一群人,很多技术人员认为人际关系比机器 ... -
文档模板,天使或恶魔?
2010-04-28 19:11 1348作者:蔡学镛 在试图建立“技术文档”时,许多人可能会想到 ... -
PPT收藏
2010-04-03 17:49 852http://tiger888.iteye.com/blog/ ... -
谈谈项目例会[转]
2010-03-28 23:18 1349在中小型系统集成公司中,项目的例会是项目团队内部沟通的主要平台 ... -
软件项目可行性分析和需求分析
2010-03-28 23:09 936http://blog.csdn.net/zhoufoxcn/ ... -
技术管理中常见的几个问题
2010-03-28 22:22 914前几天跟朋友聊天时, ... -
团队篇【转】
2010-03-22 22:11 806我一直坚信只有完美的团队,没有完美的个人! ... -
经理人技能摘取
2010-02-07 22:58 926掌控组织:http://blog.csdn.net/qinzh ... -
收藏编码规范
2010-02-03 21:11 0代码规范每家都有, 可发现开发的时候执行力很差. 所以自己小结 ...
相关推荐
你是否曾在检查代码时碰到一条在你看来多余的注释?在代码中使用注释的目的是提升代码的可读性,以让那些非原始代码开发者能更好地理解它们。 我甄别出5类让我不胜其扰的注释及5类生成它们的程序员。我希望读过...
(2)报告中有实现的关键技术点源代码,源代码书写要有一定的规范,源代码中有相关的注释; (3)作为扩展,有余力的同学,能在界面上能够定时给出可视化展示资源申请过程。 (4)实验结果要附上运行结果的截图,并...
你是否有过复查程序时发现有些注释毫无用处?程序注释是为了提高代码的可读性,为了让原作者以外的其他开发人员更容易理解这段程序。
test1:当CA组合的格式为xx-xx-xx-xx-xx(最长可识别为五位元素的组合,再长就需要修改代码) test2:当CA组合包含fourLayers test3:当CA组合缺失某种格式比如xx-xx时发现layers增加了fourlayers 功能实现: : ...
leveldb实现解析.pdf 一、 代码目录结构 ...这里对 leveldb 的实现做具体解析,但并不采用对代码注释的方式,而是意图从上层设计的角度,将内部的 实现逻辑串联起来,尽量发现策略设计背后的原因。
第十五计:引入NULL Object来避免大量的对象合法性判断 10 第十六计:函数命名有语法 10 第十七计:去除只是内部状态不同的派生类 10 第十八计:少用标记变量 12 第十九计:避免类的臃肿 13 第二十计:保持代码风格...
1.2.3 分块注释 1.2.4 语义化标签 1.2.5 引号 (三) CSS 规范 1.3.1 命名 1.3.2 选择器 1.3.3 尽量使用缩写属性 1.3.4 每个选择器及属性独占一行 1.3.5 省略 0 后面的单位 1.3.6 避免使用 ID 选择器及全局标签选择器...
1.2.3 分块注释 1.2.4 语义化标签 1.2.5 引号 (三) CSS 规范 1.3.1 命名 1.3.2 选择器 1.3.3 尽量使用缩写属性 1.3.4 每个选择器及属性独占一行 1.3.5 省略 0 后面的单位 1.3.6 避免使用 ID 选择器及全局标签选择器...
该答案为C++ Primer Plus 编程题答案,是自己在学习过程中编写的,若出现错误欢迎指正。目前还在持续学习中,后续也会不断更新新的章节。...注:有些较简单的代码可能出现代码未注释或注释较少的情况
易于扩展,避免项目开发过程中数据库结构调整所引起大量的基础类库代码维护工作,避免多个人维护同一个类时引起代码紊乱。 2、扩展存储过程说明 步骤如下: 1) 在数据库中新建存储过程; 2) 在DAL文件夹下新建分布类...
文档与注释齐全:每个项目都配有详细的文档说明和代码注释,为您的项目开发和后期维护提供便利。 易于扩展与定制:项目设计采用模块化结构,方便您根据需要进行功能扩展或定制开发。 四、使用建议 分阶段实施:...
文档与注释齐全:每个项目都配有详细的文档说明和代码注释,为您的项目开发和后期维护提供便利。 易于扩展与定制:项目设计采用模块化结构,方便您根据需要进行功能扩展或定制开发。 四、使用建议 分阶段实施:...
文档与注释齐全:每个项目都配有详细的文档说明和代码注释,为您的项目开发和后期维护提供便利。 易于扩展与定制:项目设计采用模块化结构,方便您根据需要进行功能扩展或定制开发。 四、使用建议 分阶段实施:...
文档与注释齐全:每个项目都配有详细的文档说明和代码注释,为您的项目开发和后期维护提供便利。 易于扩展与定制:项目设计采用模块化结构,方便您根据需要进行功能扩展或定制开发。 四、使用建议 分阶段实施:...
文档与注释齐全:每个项目都配有详细的文档说明和代码注释,为您的项目开发和后期维护提供便利。 易于扩展与定制:项目设计采用模块化结构,方便您根据需要进行功能扩展或定制开发。 四、使用建议 分阶段实施:...
文档与注释齐全:每个项目都配有详细的文档说明和代码注释,为您的项目开发和后期维护提供便利。 易于扩展与定制:项目设计采用模块化结构,方便您根据需要进行功能扩展或定制开发。 四、使用建议 分阶段实施:...
文档与注释齐全:每个项目都配有详细的文档说明和代码注释,为您的项目开发和后期维护提供便利。 易于扩展与定制:项目设计采用模块化结构,方便您根据需要进行功能扩展或定制开发。 四、使用建议 分阶段实施:...
18.2 在 C #代码中调用 C++和 VB 编写的组件 .240 18.3 版 本 控 制 .249 18.4 代 码 优 化 .252 18.5 小 结 .254 第五部分 附 录 .255 附录 A 关 键 字.255 附录 B 错 误 码.256 附录 C .Net 名字空间...
系统完成库存物品的管理,主要分二个大功能:一个是系统管理;一个是出入库管理。程序功能通过菜单实现,利用链表结构存贮物品信息...主要程序清单:代码及注释; 五、总结 包括遇到的困难、收获等等。不少于300字。
ASP.NET编码规范 2 第一章 编码规范概述 2 第二章 静态文件编码规范 2 ...1.1 标记的换行规范: 2 ...10、不在代码中使用具体的路径和驱动器名 15 11、人性化消息提示 15 12、多使用StringBuilder替代String 15