coding时尽量不要写注释
在学校里学习时，老师对注释的要求比较严苛。
你写代码的时候不写注释，过一段时间你自己都看不懂了，何况别人？
上一句还属于常规观点。某个老师甚至这么说：
C语言，注释量应该和代码量相当。
当时，我是心中敬仰的。然而，工作后发现，实际工程领域之中，并没有那么多注释。
而且，逐渐发现，大部分情况下不需要、也不应该注释。
由于工作中以Java为主——这真是一个悲伤的故事——以下代码以Java为例。
1. 错误的注释不如没有
注释写出来，就是给人看的。如果注释是错的，就会误导代码阅读者。
/**
* I am a boy, I like girls.
*
* @param someone is a Person who is welcome or not.
*
* @return true if someone is a Person you like.
*/
private boolean isWelcome(Person someone) {
return someone.isBoy();
}
比如上面那段，代码是个同性恋写的，注释的则是异性恋；或者，当他写注释的时候以为自己性取向很正常，写代码的时候心中忽然涌上一阵明悟……
这类注释在实际工作中碰到很多。在维护代码、或者是在以前的基础上开发代码的过程中，往往是进行增量修改。某些时候，Method内的实现已经改了，而代码注释未变，就容易出现二者不一致，甚至意义完全相反。
修改代码时，一定要先修改相关注释。这就带来了维护成本的提高。
问题是：增加的维护成本以及误导几率，是否能被注释带来的收益所抵消？
2. 没有额外语意的注释不如不写
注释不仅要说明，还必须要有额外语意，或者更简单地表达了与代码实际效果相同的意思。
public class Person {
/** The name of the Person. */
private String name;
/** The phone number of the Person. */
private String phoneNumber;
}
上面那段，这样的注释，有什么意义？
-
name不就是name吗？难道还需要再说一遍，或者翻译成中文？ -
phoneNumber不就是电话号码吗？难道要在注释里拆开，代码的阅读者才能看懂？
这类为了注释而注释的注释，除了碍眼，并无意义。而且，还容易出现第1类问题。
比如，以后人类都不用注册、购买电话号码了，直接用身份证号作为联系方式。上面的代码需要把phoneNumber改为id，修改者会不会记得改注释？
他心中一定有一万头草泥马在狂奔：还不如删掉！
3. 必要的注释是代码的失败
其实，看代码的人都是码农……呃，我是指，看代码的人都是能看代码的人。一般不会存在没有注释就看不懂的代码。
注释只不过是加速理解代码的过程。
而且，看了注释，不代表就不需要看代码。因为有可能存在第1类问题。
/**
* @return true if this is a girl and she is beautiful.
*/
public boolean isGood() {
int value = this.getValue();
// If the 1st bit of value is 0, means this is a girl.
// If the 2nd bit of value is 0, means this person is beautiful.
if ((value & 0x01) == 0 && (value & 0x02) == 0) {
return true;
} else {
return false;
}
}
以上代码中，Method的注释已经写得很清楚了，isGood()是看这个人是不是个美女。
这段注释的确加速了理解，因为isGood()并不是很直观。什么样的好才是好？
但是，为什么不把Method命名为isBeautifulGirl()？表达了同样意义的同时，也不用阅读者跳转到定义位置来看。
其次，在实现中的这段注释的确加速了理解，不然这个位操作要看很久（视脑年龄而定）。
但是，特么谁准你在Java里用位操作？！
不管你这个int里存了多少位的信息，为什么不能拆分成多个值？
如果拆分成多个值，每个值都给予恰当的命名，配以适当的Method，为什么还需要注释？
例如以下代码，需要注释吗？
public boolean isBeautifulGirl() {
return isGirl() && isBeautiful();
}
当你被自己的代码逼迫，以致要写注释之前，你应该问自己：是不是这段代码写得太糟了？要么再改改？
4. 千万不要写中文注释
虽然代码往往都是以英文为基础的，代码旁边配以大段的英文注释也确实令人抓狂。
但是比英文更令人抓狂的是乱码！
更令人抓狂的是，怎么转换都是乱码的乱码！
/**
* ��Ҳ��֪�����Ǹ�ʲô��
*/
public void doSomething() {
}
谁能把这个乱码转回去，看看我注释里写了什么？
另外，是不是有一种删掉的冲动？
好的代码本身就是注释
Person person = I.meet();
if (person instanceof Girl) {
Girl she = (Girl) person;
if (she.isBeautiful()) {
if (she.isKind()) {
I.marry(she);
} else if (she.isBitch()) {
I.fuck(she);
} else {
I.play(she);
}
} else {
I.doNothing();
}
} else {
I.stayLonely();
}
以上代码，虽然if深了一点，但是不需要注释也完全可读。哪怕从自然语言的语法角度看也问题多多，不过，代码的逻辑就在那里，比任何自然语言更准确地描述了程序的实际运行状况。
There are a thousand Hamlets in a thousand people's eyes.
一千个读者就有一千个哈姆雷特。
——莎士比亚（Shakespeare)
如果你强行要把编程语言编译成自然语言，你能确定你表达了你想表达的，你确定你想表达的就是程序实际运行的？
你确定没有犯前面的四类问题？
注释，需要是表达了和代码相同涵义（第1类问题）、而又不能是相同语意（第2类问题）、在代码比较复杂或难读（第3类问题）、并且不能用ASCII以外的字符的情况下，写在代码旁边解释代码的东西。
（其实一句话就能打败大多数中国程序员：你英文写得比代码好？）
所以，还是让一切尽在代码中吧！
Code is poetry.
log即注释
在实际的工作中，你可以不写注释，但不得不写log。
注释是写给代码阅读者看的，并不参与编译。仅存在与代码中，编译后的软件里并不存在。
而log是为了调试、后续debug的方便而添加的。良好的log，可以让我们在log文件中，看清软件的实际运行状态。
在阅读代码时，
一些例外
注释，这种语法的存在还是有必要的，只是大部分程序员其实根本用不到、或用了以后应该马上删除。
API
例如，最应该写注释的，是提供给别人——通常是另一个team、甚至公司——用的public接口，也就是所谓API。
Java的API文档，往往是通过javadoc生成的。这样的好处是，开发代码的同时开发文档，保持一致性。
不过通常不需要太多维护，因为公开的API是不能随意修改的，最大的改动往往是加一个@deprecated。
所以，其实API文档分开单独写也不是不可以。
内部用的public，代码实现都能被看见，文档也就可以免了。
实在是没有文档看不懂代码，不会问吗？
干“脏活儿”
有时候，需要表达的逻辑本身就很复杂。典型而又常见的就是多线程，往往难以理解和跟踪。
很多时候，某些语言，尤其是C语言，干的都是些“脏活儿”。为了保证性能，往往必须怎么高效怎么来。一些递归函数里，多定义一个变量，都能影响到空间复杂度。
干脏活儿，想不脏，不容易。
不过，如果真的比较复杂，还是单独的文档，或者UML图比较有效。
汇编就更不用提了。这个时代，你能写，你不能指望别人能看。
TODO和FIXME
这俩，说是注释，其实应该算是标记。
-
TODO: 表示还有未完成的工作，往往是开发过程中使用。
-
FIXME: 表示这里有bug，或者可能有bug，但暂时无法解决。这往往是发布时用。
不过，程序员的一大恨事就是：在别人release过来的代码里，发现这哥俩！
临时去掉一些代码
调试时常用注释来disable一些代码，以免删除了还得重写或粘贴。
但是，调试完成后，不要的代码一定要删掉！
结论
- 赶紧删注释去！
- 不要主动写API以外的注释！
- 代码要写得好看一点。
- 以后的工作中，谁叫写注释就有理有据地喷回去！
- 你因看了本文而产生的任何实际变化，如果在工作和学习中带来了任何负面结果，请自行负责。
网友评论
几年前改写古老的fortran程序，明白了这个道理。没有注释未来很难改写，这篇文章让人不写注释是何居心？
写注释需要把控一个度，我有一个简单的方法来把控这个度。
在写函数前，先写注释，只写函数的目的、接收参数、简略步骤、返回参数。在函数中，就不要添加注释了。
一般查看函数，都是为了看其目的与返回结果，从注释看比看复杂的代码逻辑要轻松、节约时间的多。
当然，javadoc、pydoc这些是另一回事，但也只有公开的方法、函数才会有。
另外，只看注释，不看代码，虽然省力，却永远都是高危行为。
1.开发者一般不会写错误的注释，通常是维护者造成，因为维护者可能没有写注释的习惯，也不会去改注释；
2.如果写了多余的注释，说明写代码的人本身经验不够；
3.必要的注释是为了减少阅读者的时间，降低维护成本，明显看一句话比看一大段代码来得省事；
4.文件编码问题是很容易解决的，如果是用Vim，一个命令就可以转换。另外，不一定每个人的英文都非常好，读写英文注释都可能存在理解偏差，相比之下，中文明显更不易出错。
5.每个人开发环境不同，有些语言可能确实不适合写太多注释，不可一概而论。
该有注释没有也是坑
写注释真是太艰难了
。。。。。。
另外，引用的第一句是模拟电路老师说的，第二句是量子力学老师说的……
俺是正经人，俺只是展示一段可读又吸引人的代码，俺可不是那样的人！
如果沿用你的喻体
那么
把分词符换成 空格
把分句符换成 换行符
论文是不是不影响理解
还更像诗歌了呢
---
Code is poetry.
---
至于算法，我必须同意你。
算法是最复杂的一种代码，视难度而定。它们即使是用自然语言来表达，也同样令人费解——其实这就是我所谓的“脏活儿”，注释往往是必须的。
简单的算法，如用了哪种排序，不妨写一句。但是，一句话能写清的算法，不如封装成一个Method（或Function），并赋予好的名称（你想注释的那句话）。
而复杂到一句话怎么也解释不清楚的，还是写文档比较靠谱。毕竟，代码里放不下UML图。
注释写去哪里看文档就好了。
注释就是写给人看的 -> 注释必须是自然语言 -> 我是中国人，所以注释必须是中文 -> 乱码什么的，已经阻挡不了我了，交给utf8吧。
……
直到我膝盖中了一箭……呃不，是直到不仅仅是中国人才有可能看我的代码。
javadoc虽然支持HTML，但是HTML其实并不适合作为注释，其本身并不好读，也不好写。除了对外的API，我其实不赞成写javadoc。
比注释更重要的是代码，比javadoc更重要的是README。
---
但是，当然，工作环境的要求是必须被满足的。终究，这些代码是卖给公司换工资的。
我读代码的时候一般不看注释，理解不了就要找注释。不得不说，不同人的编程习惯差异很大。
文字和代码都是我原创的。Good ideas worth spreading.
我在工作中也会查阅各类API文档，并深受其益。
---
先看注释再看代码，的确可以加速理解。良好的注释，其意义不容抹煞。
我只是认为，收益和付出并不均衡，而且可以通过和注释一样可读的代码来弥补。
毕竟，一行英文注释和一行命名良好Method，基本是等价的。
但是，我还是在实际的工作中经常遇到非utf-8格式的代码文件，以及乱码。
冏