经常看到老外的源代码里面写了一堆注释，光头部的声明就一大段。但真正到自己写的时候，发现不知道写什么，到底哪些东西该写到注释里呢？代码前面的声明应该怎么写呢？
有一种说法是，
好的代码不需要注释。
首先不同的语言，他们之间的文档注释还是有点区别的。所以你要针对不同的语言的文档认真看一下，
就拿javascript来说，虽然没有和标准的文档说明，但是一些大牛定的标准我们是可以参考的。
你说文档注释不知道写什么,那就写一些简单、基础的注释呗。比如这个函数是起什么作用，参数有哪些，参数类型是什么。更严格的还要写上作者，时间等等内容。
// _ooOoo_
// o8888888o
// 88" . "88
// (| -_- |)
// O\ = /O
// ____/`---'\____
// . ' \\| |// `.
// / \\||| : |||// \
// / _||||| -:- |||||- \
// | | \\\ - /// | |
// | \_| ''\---/'' | |
// \ .-\__ `-` ___/-. /
// ___`. .' /--.--\ `. . __
// ."" '< `.___\_<|>_/___.' >'"".
// | | : `- \`.;`\ _ /`;.`/ - ` : | |
// \ \ `-. \_ __\ /__ _/ .-` / /
// ======`-.____`-.___\_____/___.-`____.-'======
// `=---='
//
// .............................................
// 佛祖保佑 永无BUG
// 佛曰:
// 写字楼里写字间，写字间里程序员；
// 程序人员写程序，又拿程序换酒钱。
// 酒醒只在网上坐，酒醉还来网下眠；
// 酒醉酒醒日复日，网上网下年复年。
// 但愿老死电脑间，不愿鞠躬老板前；
// 奔驰宝马贵者趣，公交自行程序员。
// 别人笑我忒疯癫，我笑自己命太贱；
// 不见满街漂亮妹，哪个归得程序员？
注释表达清楚为什么要这样做比做了什么更重要.
一般头部不都是许可相关的内容么……
文档注释的话一般就是一些工具生成的：doxygen , jsdoc 酱紫。
关于什么时候才需要写注释，我同意 @依云 在 @王子亭 文章中的评论：http://blog..com/jysperm/1190000000620847?page=1#c-1190000000620847-1050000000621782
头部是文档性质的注释，可能是给ide做提示用的。
最好的写代码注释的方式就是当你感觉到“OOPS我觉得这地方一定要说明一下不然谁都看不懂”的时候果断写下注释
用自然语言把你要做的事情描述一遍，再来根据你的描述写代码。要描述得足够清楚，让别人看到你的注释都能把代码写出来——这大概就是你说的那些老外的作法。
另外还有一类注释是文档注释，就是把要暴露出来的元素都写上注释，最后用一个工具从代码把文档生成出来，比较 javadoc 和 C# 的文档注释都是这一类。
不过一般情况下我不赞成写大量注释（文档注释除外），应该尽可能的使用自注释的名称来代替。在实在逻辑比较复杂，或者比较绕的地方写点注释说明一下就好了。如果源文件特别多，可以在文件头写一个简单的注释说明下这个源文件的代码是干啥的。或者干脆就在目录下写个README。
给另外一个水平差不多的程序员读，他觉得难以理解的地方，你写下注释就行了。
首先，你的本職工作不是寫代碼，而是思考。
寫代碼不是目的，而是手段。
註釋也是手段，只不過和代碼讓計算機理解不同，註釋讓他人和自己理解。
「怎樣」寫，你是問方法。方法歸根結底還是一種手段。可無論何種方法，只要你沒有足夠的思考，寫出來的註釋一樣會空洞無味。
你需要的不是方法，不是手段。而是目的。你爲何而寫？
哈哈,你好. 说说自己写注释的一些习惯吧.
类的头部一般会去添加关于这些类的一些基本信息.
1. 这个类是用来干什么的实现哪些功能.
2. 这个类当中是否存在一些比较特殊的机制.如果有会去把机制描述清楚,有两个好处 第一就是去帮助自己去理清思路,第二就是当别人在阅读你的代码时会更加的轻松.(我自己对分包是有强迫性，一般先会按架构去分包,在去按业务去分包.)
3. 一般方法不怎么写注释. 就是去名字写得老长. buildActionBarAndViewPagerTitles();
微笑一个！
注释是离职时最好的盾牌。。