编写易读的代码

这种编写注释块来生成API文档的做法可不仅仅是为了偷懒，它还有另外一个作用，就是通过回头重看代码来提高代码质量。

随便一个作者或者编辑都会告诉你“编辑非常重要”，甚至是写一本好书或好文章最最重要的步骤。将想法落实在纸上形成草稿只是第一步，草稿确实可以给读者提供不少信息，但往往还不是重点最明晰、结构最合理、最符合阅读习惯的呈现形式。

编程也是同样的道理，当你坐下来解决一个问题的时候，这时的解决方案只是一种“草案”，尽管能正常工作，但是不是最优的方法呢？是不是可读性好、易于理解、可维护和更新？假设当你过一段时间后再来回头看你的代码，一定会发现很多需要改进的地方，比如需要重新组织代码或删掉多余的内容等等。这实际上就是在“整理”你的代码了，可以很大程度上提高你的代码质量。但事实却不那么如愿，我们常常承受着高强度的工作，根本没有时间来整理代码，因此通过代码注释来写文档其实是个不错的机会。

你往往会在写注释文档的时候发现很多问题，也会重新思考代码中的不合理之处，比如，某个方法中的第三个参数比第二个参数更常用，第二个参数多数情况下取值为true，因此就需要对这个方法进行适当的改造和包装。

写出易读的代码（或API），是指写代码时要有让别人能轻易读懂的意识。带着这个意识，你就需要不断思考采用更好的方法来解决手头的问题。

说回“草稿”的问题，也算是“抱佛脚”的权宜之计，一眼看上去是有点“草”，不过至少是有用的，特别是当你处理的是一个关键项目时（比如人命关天时）。一个合适的思路是，你应当始终扔掉你所给出的第一个解决方案，虽然它是可以正常工作的，但毕竟是一个草稿，是一种仅用于验证解决问题可行性的方案。事实上，第二个方案往往会更好，因为这时你对问题的理解会更加透彻。在产生第二个方案的过程中，不要允许自己去复制粘贴之前的代码，这有助于阻止自己投机取巧利用之前的捷径，最后产生不完美的方案。