我为什么拒绝写注释

zhangxuguang2007 2011-05-25 05:23:35
看了一篇博文《我为什么拒绝写注释》 ,看了回帖,反对声音一边倒。但我和作者深有共鸣,于是写一篇博文以示声援。

注释本质上是另一种形式的文档,当我们来讨论注释的必要性的时,其实就是在讨论文档的必要性。注释和文档确实可以带给我们一些收益,但使用不当却会带来很多的麻烦.

1.可运行的代码是唯一正确反映现实的东西。需求是易变的,因此软件也是易变的,但是绝大多数公司/团队都没有精力和财力来及时的更新文档和注释,因此越到项目后期,就会越会出现注释(文档)和代码不一致的情况。于是程序中充满了虚假的注释和谎言。

2.当你需要用注释来说明自己的算法和意图的时候,停下来想一想,很多时候你会发现自己的设计出了问题。很少会出现这种情况:需要牺牲程序的可读性来提高效率。因为精心设计的代码往往是简练的,简练往往是高效的。

3.过多的注释往往会干扰程序的可读性,频繁出现的注释是一种糟糕的排版体验。试想一下,如果你正在阅读一篇论文,论文的注释随时出现文章的正文中,这是多么令人沮丧的一件事。

4.不要拿MSN和Framework的注释来说事。这不是一个技术问题,而是一个商业问题。Framewrok的核心价值就是代码本身,而不是具体的业务应用,因此注释也是Framework的核心价值。而你的软件的核心价值是可运行的程序以及其后的业务逻辑。在微软公司,注释往往由专业的文档管理团队来处理,你的公司又有这样的实力吗?

5.我们并不排斥一切文档,但我只给软件最核心,最稳定的部分编写文档,例如软件的架构。另一方面,我坚持严格把软件的文档控制在20页以内,这样可以使一个新人在一天之内了解程序最核心的部分,通过可运行的软件,新人才会建立起真正的自信和对项目全面的认识。至于更具体的细节应该在工作中了解。

最后附上《敏捷宣言》供大家参考
#个体和交互 胜过 过程和工具
#可以工作的软件 胜过 面面俱到的文档
#客户合作 胜过 合同谈判
#响应变化 胜过 遵循计划
虽然右项也有价值,但是我们认为左项具有更大的价值。
...全文
1548 90 打赏 收藏 转发到动态 举报
AI 作业
写回复
用AI写文章
90 条回复
切换为时间正序
请发表友善的回复…
发表回复
little_elle 2011-08-08
  • 打赏
  • 举报
回复
为什么不认为好的注释+好的代码才是最好的组合呢?

代码是自会说话,就算看不懂你写的代码是他水平不行,难道你的代码就限定为牛X程序员才能维护?

那么能写出任何水平程序员都容易维护的代码(在软件各指标一致的情况下),是否更牛X呢?

不写注释唯一的好处是,这部分代码让人难以上手,公司一时半会离不了你。
plusuu 2011-08-07
  • 打赏
  • 举报
回复
注释是必须的。。。
tantaiyizu 2011-08-06
  • 打赏
  • 举报
回复
支持楼主
wyang1991 2011-08-06
  • 打赏
  • 举报
回复
如果你的代码是给你自己看的,维护也是你自己,那么没问题,自作自受。

如果你的代码是交给别人维护的,那么积点德吧

就是你的代码是给你自己看的,N年之后,你还记得当初是怎么想的吗,如果不记得了,不要骂娘就行

over!
hawk_js 2011-07-29
  • 打赏
  • 举报
回复
还是有注释好一点!
jfan288 2011-07-27
  • 打赏
  • 举报
回复
晕,technology writter在楼主眼里怎么成了写代码注释的了
cjwell 2011-07-23
  • 打赏
  • 举报
回复
没注释,自己写过的代码自己也看不懂
cfvmario 2011-07-22
  • 打赏
  • 举报
回复
[Quote=引用 42 楼 jackzhhuang 的回复:]
楼主的意思是:只要代码写得好(命名好,架构好,代码整洁),注释就是多余。
而我的意思是:代码写得再怎么好,注释也是必须的,因为注释是人类语言,程序代码是怎么都比不过的。
[/Quote]
这2者都极端了。
首先编程时要时刻想着代码的可读性
其次当你想用注释提高代码可读性时,要确认这不是用代码本身能做到的。很糟糕的事情之一是,不少代码需要加注释来让人看懂,是因为诸如变量函数命名不自明之类的问题。
糟糕代码+补注释毕竟不如好代码能直接看懂最好。在复杂数据结构的定义处,通常还是需要注释来说明各个字段是干什么的。但是在代码中写注释并不总是必需的
zhangxuguang2007 2011-07-22
  • 打赏
  • 举报
回复
[Quote=引用 72 楼 fellatioyzx 的回复:]
我们团队里就有个人,思想跟别人不一样,维护他的代码时明明看得到结果是对是错,但是你就不知道他为什么这么写,搞得我们总要去问他,难道这个时候还不需要个关于“为什么”的注释么?
[/Quote]
代码应该自己说话
  • 打赏
  • 举报
回复
有一定的道理
velantino1 2011-07-13
  • 打赏
  • 举报
回复
如果不是复杂的代码,应该看代码就能知道是什么意思,否则就是你功夫不扎实
velantino1 2011-07-13
  • 打赏
  • 举报
回复

太复杂的代码写不写注释都一样,都看不懂。

比如下面这个函数,本人建议只要逻辑判断超过5个子级的,有没有注释都不要看了,此乃杀人不见血的利器
function delVal() {
if (confirm("确定要删除选中的?")) {
var rad = document.getElementsByName("Vhead");
var statS = false;
for (var i = 0; i < rad.length; i++) {
var srd = rad[i].id;
var chks = document.getElementsByName("c" + srd);
var chkVals = document.getElementById("t" + srd).value;
var stat = false;
for (var l = chks.length - 1; l > -1; l--) {
if (chks[l].checked) {
stat = true;
statS = true;
var chk = chks[l].value;
if (srd == "rb2" || srd == "rb31") {
var chkwheres = chkVals.split('⌒')[1].split('┃');
for (var k = 0; k < chkwheres.length; k++) {
if (chkwheres[k].indexOf(chk + "┼") >= 0) {
var oneObjS = chkwheres[k].replace(chk + "┼", "");
if (chk.substring(0, 1) == "┘")
oneObjS = oneObjS.replace("┤)" + chk.split('∷')[chk.split('∷').length - 1] + "┼", "");
var oneObj = oneObjS.split('┼');
if ((oneObj[0].substring(0, 1) == "│" || (oneObj[0].substring(0, 6) == "where∷" && oneObj[1].substring(0, 1) == "│") || oneObj[oneObj.length - 2].substring(0, 1) == "│") && k < chkwheres.length - 1) {
if (oneObj[0].substring(0, 6) == "where∷")
chkVals = chkVals.replace(chkwheres[k].replace(oneObj[0] + "┼", "") + "┃" + chkwheres[k + 1].split('┼')[0] + "┼", "");
else
chkVals = chkVals.replace(chkwheres[k] + "┃" + chkwheres[k + 1].split('┼')[0] + "┼", "");
}
else if (oneObj[0].substring(0, 1) == "│" || (oneObj[0].substring(0, 6) == "where∷" && oneObj[1].substring(0, 1) == "│") || oneObj[oneObj.length - 2].substring(0, 1) == "│") {
chkVals = chkVals.replace("┃" + chkwheres[k], "");
chkVals = chkVals.replace(chkwheres[k], "");
}
}
}

}
var orderVals = chkVals.split('┼');
for (var k = 0; k < orderVals.length - 1; k++) {
if(orderVals[k] == chk)
{
if(k>0&&k<orderVals.length-2){
if((orderVals[k+1].substring(0,1)=="┨"&&orderVals[k-1].substring(0,1)=="╂")||(orderVals[k+1].substring(0,1)=="╂"&&orderVals[k-1].substring(0,1)=="│")){
chk="┠("+orderVals[k+1].substring(2);
}
else if(orderVals[k+1].substring(0,1)=="│"&&orderVals[k-1].substring(0,1)=="┠"){
chk=orderVals[k-1];
}
}
}
if (orderVals[k].substring(0, 1) == '┆') {
if (((parseInt(chk.split('∷')[2]) + 1) + "") == orderVals[k].split('∷')[2]) {
chkVals = chkVals.replace(orderVals[k] + "┼", "");
break;
}
}
}
if(chk.substring(0, 1) == '┯')
{
//┯判断语┷┠判断╂分隔符┨
chk=chkVals.substring(chkVals.indexOf(chk+"┼"),chkVals.indexOf("┷)"+chk.substring(2)+"┼")+chk.length);
}
if(chk.substring(0, 1) == '┠')
{
chk=chkVals.substring(chkVals.indexOf(chk+"┼"),chkVals.indexOf("┨)"+chk.substring(2)+"┼")+chk.length);
}
chkVals = chkVals.replace(chk + "┼", "");
if (chk.substring(0, 1) == "┘")
chkVals = chkVals.replace("┤)" + chk.split('∷')[chk.split('∷').length - 1] + "┼", "");
else if (chk.substring(0, 1) == "┬" || chk.substring(0, 1) == "┴") {
chkVals = chkVals.replace(chk.replace("┬(", "┴)") + "┼", "");
chkVals = chkVals.replace(chk.replace("┴)", "┬(") + "┼", "");
}
}
}
if (stat) {
document.getElementById("t" + srd).value = chkVals;
viewCheckbox(srd);
if (srd == "rb3")
groupView();
}
}
if (statS)
savePageVal();
}

return false;
}



Louis-Lv 2011-07-06
  • 打赏
  • 举报
回复
要我看没注释的代码 还不如杀了我。。 虽然我看过好几次了。。 生活所迫啊!!!!
cuiy0002 2011-07-02
  • 打赏
  • 举报
回复
Do not over-comment.
小竹z 2011-06-29
  • 打赏
  • 举报
回复
我刚进了一家公司,现在正在维护和扩展以前写得代码,大约有40多万行,现在最头疼的就是很多没有注释。楼主没遇到,遇到你还会这样想吗?
  • 打赏
  • 举报
回复
注释有它自己的格式和规范。

极度不规范的注释,还不如没有,这是事实。

写不规范的解决办法是如何写规范,而不是不要这个东西。


我觉得
  • 打赏
  • 举报
回复
因为注释写的不对,所以就不提倡写注释。

这是什么逻辑?注释和代码不一致,是开发人员本身垃圾的问题,跟代码需不需要注释能直接挂钩?

就好像...因为一些公司,有些冗余代码,所以开发的时候,不提倡写代码!!!
yueyueniao777 2011-06-29
  • 打赏
  • 举报
回复
不写注释,有些极端

由于需求变化,而拒绝写注释,那是你水平不够,好的设计,必须要能应对变化。

注释写得少,但是却代码很好读懂,那才是高手,
因为你的代码就是注释。

OK???
fellatioyzx 2011-06-28
  • 打赏
  • 举报
回复
我认为团队里不是每个人都有Martin Fowler的水平,但是大凡是人的多少都有一点“认为自己的代码可以算超过Martin Fowler水平”的自信。

我相信LZ拒绝注释是一种提高自己编码质量的“逼迫”(我没有贬义啊,只是想说这是个很手段),但是你真的能确定,团队里每个人所认为的“自己意义下的高质量代码”都能被队友接受么?别忘了,即使是编码习惯也是有不同的。

我们团队里就有个人,思想跟别人不一样,维护他的代码时明明看得到结果是对是错,但是你就不知道他为什么这么写,搞得我们总要去问他,难道这个时候还不需要个关于“为什么”的注释么?
wing_0706 2011-06-13
  • 打赏
  • 举报
回复
[Quote=引用 12 楼 pike_feng 的回复:]
看代码了,我见过有的程序所有变量都是单个字母往下排:
int a,b,c;
String d,e,f;
bool g,h,i;
int aaa();
char bbb();
……

这样的程序不加注释看着确实费劲!
[/Quote]
杀了我吧……
加载更多回复(70)

662

社区成员

发帖
与我相关
我的任务
社区描述
提出问题
其他 技术论坛(原bbs)
社区管理员
  • community_281
加入社区
  • 近7日
  • 近30日
  • 至今
社区公告
暂无公告

试试用AI创作助手写篇文章吧