代码精进之路
范学雷
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讲)
结束语｜如何成为一个编程好手？
代码精进之路
登录|注册
14 | 怎么写好用户指南？
范学雷 2019-02-04
前一段时间，我要买一部家用的跑步机。有一款跑步机看起来配置齐备，商品的标题中指明“需要组装”。
商品的评论只有两条。其中一条给了三分：“还没有来得及试一试这个新到的跑步机。因为，我一直试着把它组装起来。我做梦都没有想到，‘需要组装’意味着我花了三天时间，都没有组装起来。它也许是一个好的跑步机，可是令人失望的是，这些零件到底该怎么凑在一起！”
而另一条则给了最低的一分。评论写道：“商品描述不准确。这台机器非常重，长度甚至超过两人沙发。一般的家庭根本放不下这台跑步机。已经退货了”。
你可以想象，这两条仅有的评论对这款跑步机的销售有多大的杀伤力。它本身的品质无论如何，都不至于沦落到一分、三分的地步。
问题在哪儿呢？无论是谁，花了三天时间都搞不定组装，肯定有一肚子的不满意。好不容易组装起来，却发现没有空间放置，又要拆掉退货，就会更不满意。
我了解了一下这款跑步机的用户手册，发现组装非常繁琐，所涉及的部件有很多，还真不是一下子就可以搞定的。
很显然，用户指南非常重要，但这款跑步机却给我们提供了一个反面的案例，可见写出一份好的用户指南也不是一件容易的事。
最好的用户指南，是产品本身。我们随手拿一只圆珠笔，就知道怎么用。然而，不是所有的产品都能够简单到拿来就用。一份合格的用户指南，要帮助用户减少产品使用的障碍，快速地使用产品。
取消
完成
0/1000字
划线
笔记
复制
© 版权归极客邦科技所有，未经许可不得传播售卖。 页面已增加防盗追踪，如有侵权极客邦将依法追究其法律责任。
该试读文章来自付费专栏《代码精进之路》，如需阅读全部文章，
请订阅文章所属专栏。
请订阅文章所属专栏。
立即订阅
登录 后留言
精选留言(8)
北风一叶我之前的主管给我的建议是这样的：你就把用户假定为啥也不理解然后再去写文档，写出来的文档就是合格的作者回复: 这是一个好办法。经常地，我们看一些文档，觉得废话太多，大量的篇幅交代背景。其实，哪是为了照顾更多的用户。
2019-03-11 2- kelvin我提出要给服务的接口写wiki，但是领导说大家都不会维护，还不如直接问接口维护人。我觉得维护文档是大家不太习惯，但是长远来看是可以提高开发效率。
作者回复: 直接问接口维护人的问题很多： 接口维护人不一定时刻都在；接口维护人不一定有那么多时间；接口维护人不一定记得那么多细节；我们不一定想要面对面地提问；面对面问问题的效率有可能更低（复杂的技术问题需要问答双方都花很多时间）。
2019-04-03 1 
空知微信和Github的示例都只是提供示例,但是一些前提概念没有说明下吧.作者回复: 嗯，引用的是快速入门部分。
2019-02-15 1
丁丁历险记身为py coder 我内心纠结之处，一直觉得java 反人类，经常一个简单事搞的啰哩巴嗦的，一度认为再好的设计模式也救不了java 的不优雅。
甚至看到java 的代码示例看着就浅意识排斥。
现在技术到了瓶颈期，在反思如何改善这些观点，我可以不喜欢，但个人鲁棒性需要加强。2019-10-14- Sisyphus235用户指南就像是开发者的 PPT，一个好的产品还要有一个漂亮的展示才能有价值。
例证丰富能快速上手实践的往往是好的用户指南，在写文档的时候，文字和代码以及例证交叉，再配合一些图效果比较好，另外使用总分的结构效果比较好2019-05-22 
Lindroid今年我也在GitHub上添加了两三个开源库（主要是供自己使用），不得不说写好说明文档真的是不容易的，而且比起最初的编写，后期的维护也考验人。作者回复: 😊经久耐用的软件，成本基本都在维护上。
2019-04-27
秦凯个人理解是：接口规范应该更多的是描述接口为什么这么设计，而用户指南更多的是指导用户如何使用接口，阅读的群体和功能上有区别。作者回复: 在 Java SE里，接口规范一般不包括“为什么这么设计”的描述。
2019-02-15
vector简单明了，考虑全面。佩服别人家的手册。2019-02-08
收起评论