代码精进之路
范学雷
Oracle首席软件工程师，Java SE安全组成员，OpenJDK评审成员
立即订阅
6350 人已学习
课程目录
已完结 47 讲
0/4登录后，你可以任选4讲全文学习。
开篇词 (1讲)
开篇词 | 你写的每一行代码，都是你的名片
免费
第一模块：代码“规范”篇 (16讲)
01 | 从条件运算符说起，反思什么是好代码
02 | 把错误关在笼子里的五道关卡
03 | 优秀程序员的六个关键特质
04 | 代码规范的价值：复盘苹果公司的GoToFail漏洞
05 | 经验总结：如何给你的代码起好名字？
06 | 代码整理的关键逻辑和最佳案例
07 | 写好注释，真的是小菜一碟吗？
08 | 写好声明的“八项纪律”
09 | 怎么用好Java注解？
10 | 异常处理都有哪些陷阱？
11 | 组织好代码段，让人对它“一见钟情”
12丨组织好代码文件，要有“用户思维”
13 | 接口规范，是协作的合约
14 | 怎么写好用户指南？
15 | 编写规范代码的检查清单
16丨代码“规范”篇用户答疑
第二模块：代码“经济”篇 (14讲)
17 | 为什么需要经济的代码？
18丨思考框架：什么样的代码才是高效的代码？
19 | 怎么避免过度设计？
20 | 简单和直观，是永恒的解决方案
21 | 怎么设计一个简单又直观的接口？
22丨高效率，从超越线程同步开始！
23 | 怎么减少内存使用，减轻内存管理负担？
24 | 黑白灰，理解延迟分配的两面性
25 | 使用有序的代码，调动异步的事件
26 | 有哪些招惹麻烦的性能陷阱？
27 | 怎么编写可持续发展的代码？
28 | 怎么尽量“不写”代码？
29 | 编写经济代码的检查清单
30丨“代码经济篇”答疑汇总
第三模块：代码“安全”篇 (14讲)
31 | 为什么安全的代码这么重要？
32 | 如何评估代码的安全缺陷？
33 | 整数的运算有哪些安全威胁？
34 | 数组和集合，可变量的安全陷阱
35 | 怎么处理敏感信息？
36 | 继承有什么安全缺陷？
37 | 边界，信任的分水岭
38 | 对象序列化的危害有多大？
39 | 怎么控制好代码的权力？
40 | 规范，代码长治久安的基础
41 | 预案，代码的主动风险管理
42 | 纵深，代码安全的深度防御
43 | 编写安全代码的最佳实践清单
44 | “代码安全篇”答疑汇总
加餐 (1讲)
Q&A加餐丨关于代码质量，你关心的那些事儿
结束语 (1讲)
结束语｜如何成为一个编程好手？
代码精进之路
登录|注册
07 | 写好注释，真的是小菜一碟吗？
范学雷 2019-01-18
上一讲中我们讲了如何整理代码，但有些时候，即便我们取好了名字，编排好格式，但代码还是让我们抓狂，不明出处，不好理解。这时候，就需要注释登场了。
顾名思义，注释就是对代码的解释。注释不需要运行，它是用来提高代码的可读性和可维护性的。不好的注释会使代码变得更糟糕，使人更抓狂。
理想虽丰满，现实很骨感。注释虽小，写好不易。那写注释有哪些注意事项？有没有什么技巧呢？今天我们就来聊聊写注释这个话题。
当然了，不同的语言，注释的语法差别很大。为方便起见，我们统一使用 Java 语言的注释语法，来解释说明写好注释的基础原则。
注释是无奈的妥协
那你是不是有这样一个问题，源代码一定需要解释吗？
其实在理想状况下，代码不需要注释。理想的代码，命名恰当，结构清晰，逻辑顺畅，含义显而易见。但正如一个作家无法预料他的读者能否清晰地理解他的文字一样，一个程序员也不能判断他的读者能否清晰地理解他写的代码。所以，写注释其实是下巧功夫。
可是，注释也是一个麻烦鬼，可能会给我们带来三个麻烦。
首先，因为注释不需要运行，所以没有常规的办法来测试它。 注释对不对？有没有随着代码变更？这些问题都是写注释需要注意的地方。注释难以维护，这是使用注释带来的最大的麻烦。
取消
完成
0/1000字
划线
笔记
复制
© 版权归极客邦科技所有，未经许可不得传播售卖。 页面已增加防盗追踪，如有侵权极客邦将依法追究其法律责任。
该试读文章来自付费专栏《代码精进之路》，如需阅读全部文章，
请订阅文章所属专栏。
请订阅文章所属专栏。
立即订阅
登录 后留言
精选留言(19)
秦凯Code Tells You How, Comments Tell You Why.2019-01-18 32
L要写好注释首先要思考怎么不写注释2019-01-18 9
彩色的沙漠通过本篇学习，自己写的注释犯了两个错误一是提交了注释掉的测试代码和需求变更后不需要的代码，二是使用了TODO提醒自己，写完之后没有删除。
老师最后讲的五种风格，第三种风格和第四种风格有什么区别，只发现了颜色区别，其他的一样作者回复: 第三种风格和第四种风格区别在方法的命名上。嗯，不太容易看出来。
2019-01-18 4- 有渔@蔡尽量不写注释，尽量用代码告诉别人我的思想。注释用来写代码无法表达的东西，比如我当时为什么这么写，其他想法等。2019-03-01 2
Being建议注释用英文，确实，中文注释还不好排版。关键是团队建议用中文，好无奈，而且写着写着还要切换输入法2019-01-18 2
小智e不要在源代码里记录代码历史，那是代码版本管理系统该干的事情。有时候需求变更，一些程序员会把之前的代码注释掉，觉得如果 PM 脑回来，某一天就换回来了，就避免重复写了。这样做会有一个缺点，就是如果其他程序员接手了这份代码，不了解上下文，不知道注释调的代码是干嘛的，也不敢删，这份注释的代码就像僵尸进程一样，一直存在代码中。2019-11-08 1
小新是也在代码写TODO已成为团队的习惯作者回复: 嗯，曾经常用的标记。有些人还保留了这个习惯，并且传承了下来。
2019-01-27 1- 如摄作为前端人员买了这个专栏，收获也不少……
能不能针对js讲一个课程。作者回复: 这是个好主意！
2019-01-24 1 - Sisyphus235留言区没有人讨论课后题，我抛砖引玉下。注释就像文中所说，准确、必要和清晰最重要，也就是说在不同的团队同一段代码的注释会不同，因为团队能力不同。这里我试着用比较完整的方式做一段注释，如果团队能力好，一些部分是可以省略的
import java.util.HashMap;
import java.util.Map;
class TwoSumSolution {
/**
* Given an array of integers, return indices of the two numbers
* such that they add up to a specific target.
*/
public int[] twoSum(int[] nums, int target) {
// init a map storing number and its index relation
Map<Integer, Integer> map = new HashMap<>();
for (int i = 0; i < nums.length; i++) {
// calculate the complement of current number
int complement = target - nums[i];
// if map contains the complement, return complement directly, else update map with current number
if (map.containsKey(complement)) {
return new int[] { map.get(complement), i };
}
map.put(nums[i], i);
}
// if the sum of any two numbers is not equal to the specific target, throw illegal argument exception
throw new IllegalArgumentException("No two sum solution");
}
}作者回复: 👍
2019-05-22 
卞雪达如果一段代码不再需要，我会清理掉代码，而不会保留这个注释掉的代码块。
--我简直不能再同意了，我曾因为错误的注释代码而导致十几万的损失，我那时候测试分支特别喜欢用注释代码的方式，因为在一个文件甚至方法里复制并注释两下，是很快能达成一个分支的。这种错误的习惯一旦养成，隐患大大滴。正如您说的，这种情况应该使用版本控制。切换的时候，应该切换不同版本的文件。确定的分支如判断开发环境或生产环境，我喜欢用配置文件…应该，是受到前端套路的影响，你知道各种前端框架都喜欢isDev，我慢慢的…觉得好像还不错…作者回复: 我可能要极端一点，配置文件可以，但是判断是开发环境还是生产环境的，然后使用不同分支的代码不应该出现，也是一大堆的问题。
2019-05-14
10rina－f刚开始工作的时候，自己写了一段代码（没有什么注释），过来一段时间，自己维护的时候花了很多时间来读自己的代码。。。深刻明白了注释的重要性（虽然当时代码写的不好也有一部分原因）作者回复: 是的，自己也是未来的阅读者之一。
2019-04-10- 老吴建议英文 ，但是我们团队都是第二种，我们英语水平一般
作者回复: 第二种也是很好的。
2019-02-21 
北风一叶我从来没在注释里用过｛code userName｝这样的用法，以后需要改进作者回复: 嗯，防止指代不明。
2019-02-20
小文还是喜欢中文，文中的indices就不知道啥意思，翻译后才知道是指数，有时候看英文注释个别单词不认识很郁闷😒作者回复: 随着视野的不断扩张，早晚会习惯英文的。
2019-02-15
峰人院第三四五种不用是因为用了拼音吧🤣，第五种注释有问题，注释没有完结的 /，后面的代码都不能用啦，谢谢老师指点作者回复: 嗯，我漏掉了尾部注释符号这一行。 谢谢！
2019-01-24
虢国技匠打卡2019-01-20
草原上的奔跑老师最后留的题看半天才发现是返回两个数的索引，这两个数的和为target，若不存在，则抛出异常，方法的注释应该把异常抛出的情况也讲出来，同时，注释中的indicate感觉改为index更好理解。作者回复: 练手题的注释缺了很多注释，难以理解。已经有的注释，使用的也不规范。你找到的两个都是很好的改进。
2019-01-18
Demon.Lee老师，如果我有一个函数，只是先写了一个空函数（类似于定了一个接口），这个时候我会写个注释说待完善，感觉是不是也不能写了？我感觉这有点类似于警告的性质，就是说提醒开发者，后续要注意作者回复: 空函数有人使用吗？ 没人用要删掉，有人用函数的功能要清楚。
有的时候，的确需要一些提醒类的东西，但是要标记清楚问题，不要含混。 要不然，一旦忙起来，忘记了修改，以后自己看到都记不起来了。OpenJDK的代码里就有不少这样的失误，改起来很费精神，要校对注释和代码，比重写一遍都麻烦。
当然，代码没提交之前，特别是编码和调试的时候，可以多用些注释提醒下。我一般会把这样的注释和代码，顶格些，提交之前浏览下，这样就不容易忘记删除了。2019-01-18
王智心酸,被打击到了,表示毕业半年,在校英语就不好,现在依旧,看到要用英文写注释表示头疼,一直想学好英语但不知道从哪里下手,看来下去得多尝试尝试英语了,增强一下英语水平,不然就只能使用idea的插件进行翻译了,(╥╯^╰╥)!!!作者回复: 写代码的，那么多的英文文献要看，英文想不好都不太容易。时间长点，就适应了。
2019-01-18
收起评论