我为什么拒绝写注释

[zhangxuguang2007]

看了一篇博文《我为什么拒绝写注释》 ，看了回帖，反对声音一边倒。但我和作者深有共鸣，于是写一篇博文以示声援。

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

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

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

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

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

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

最后附上《敏捷宣言》供大家参考
#个体和交互 胜过 过程和工具
#可以工作的软件 胜过 面面俱到的文档
#客户合作 胜过 合同谈判
#响应变化 胜过 遵循计划
虽然右项也有价值，但是我们认为左项具有更大的价值。

[wing_0706]

[Quote=引用 12 楼 pike_feng 的回复:]
看代码了，我见过有的程序所有变量都是单个字母往下排：
int a,b,c;
String d,e,f;
bool g,h,i;
int aaa();
char bbb();
……

这样的程序不加注释看着确实费劲!
[/Quote]
杀了我吧……

[fellatioyzx]

我认为团队里不是每个人都有Martin Fowler的水平，但是大凡是人的多少都有一点“认为自己的代码可以算超过Martin Fowler水平”的自信。

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

我们团队里就有个人，思想跟别人不一样，维护他的代码时明明看得到结果是对是错，但是你就不知道他为什么这么写，搞得我们总要去问他，难道这个时候还不需要个关于“为什么”的注释么？

[yueyueniao777]

不写注释，有些极端

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

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

OK？？？

[别吵_我睡会儿先]

因为注释写的不对，所以就不提倡写注释。

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

就好像...因为一些公司，有些冗余代码，所以开发的时候，不提倡写代码！！！

[别吵_我睡会儿先]

注释有它自己的格式和规范。

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

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


我觉得

[小竹z]

我刚进了一家公司，现在正在维护和扩展以前写得代码，大约有40多万行，现在最头疼的就是很多没有注释。楼主没遇到，遇到你还会这样想吗？

[cuiy0002]

Do not over-comment.

[Louis-Lv]

要我看没注释的代码 还不如杀了我。。 虽然我看过好几次了。。 生活所迫啊！！！！

[velantino1]

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

比如下面这个函数，本人建议只要逻辑判断超过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;
}

[velantino1]

如果不是复杂的代码，应该看代码就能知道是什么意思，否则就是你功夫不扎实

[软件架构师何志丹]

有一定的道理

[zhangxuguang2007]

[Quote=引用 72 楼 fellatioyzx 的回复:]
我们团队里就有个人，思想跟别人不一样，维护他的代码时明明看得到结果是对是错，但是你就不知道他为什么这么写，搞得我们总要去问他，难道这个时候还不需要个关于“为什么”的注释么？
[/Quote]
代码应该自己说话

[cfvmario]

[Quote=引用 42 楼 jackzhhuang 的回复:]
楼主的意思是：只要代码写得好（命名好，架构好，代码整洁），注释就是多余。
而我的意思是：代码写得再怎么好，注释也是必须的，因为注释是人类语言，程序代码是怎么都比不过的。
[/Quote]
这2者都极端了。
首先编程时要时刻想着代码的可读性
其次当你想用注释提高代码可读性时，要确认这不是用代码本身能做到的。很糟糕的事情之一是，不少代码需要加注释来让人看懂，是因为诸如变量函数命名不自明之类的问题。
糟糕代码+补注释毕竟不如好代码能直接看懂最好。在复杂数据结构的定义处，通常还是需要注释来说明各个字段是干什么的。但是在代码中写注释并不总是必需的

[cjwell]

没注释，自己写过的代码自己也看不懂

[jfan288]

晕，technology writter在楼主眼里怎么成了写代码注释的了

[hawk_js]

还是有注释好一点！

[wyang1991]

如果你的代码是给你自己看的，维护也是你自己，那么没问题，自作自受。

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

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

over！

[tantaiyizu]

支持楼主

[plusuu]

注释是必须的。。。

[little_elle]

为什么不认为好的注释+好的代码才是最好的组合呢？

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

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

不写注释唯一的好处是，这部分代码让人难以上手，公司一时半会离不了你。