比如这里有一个函数reverse()，可以对字符串进行反序操作。它的参数和返回值都是字符串。给它补充注释如下：

这种将APIDoc格式的代码注释解析成API参考文档的做法看起来很偷懒，但还有另外一个目的，通过代码重审来提高代码质量。

很多作者或编辑会告诉你“编辑的步骤非常重要”，甚至是写一本好书或好文章最重要的步骤。将想法落实在纸上形成草稿只是第一步，草稿给读者提的信息往往重点不明晰、结构不合理、或不符合循序渐进的阅读习惯。

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

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

写出易读的代码（或API），是指别人能轻易读懂程序的思路。所以你需要采用更好的思路来解决手头的问题。

尽管我们认为“草案”不甚完美，但至少也算“抱佛脚”的权宜之计，一眼看上去是有点“草”，不过也无所谓，特别是当你处理的是一个关键项目时（会有人命悬与此）。其实你应当扔掉你所给出的第一个解决方案，虽然它是可以正常工作的，但毕竟是一个草率的方案，不是最佳方案。你给出的第二个方案会更加靠谱，因为这时你对问题的理解更加透彻。第二个方案不是简单的复制粘贴之前的代码，也不能投机取巧寻找某种捷径。

另外一种可以提高代码质量的方法是组织相互评审。同行的评审很正式也很规范，即便是求助于特定的工具，也不失是一种开发生产线上值得提倡的步骤。但没有时间互审或采用工具并不是问题，你可能觉得没有时间去组织代码互审，没关系，你可以让坐在你旁边的同事读一下你的代码，或者和她（译注：注意是“她”而不是“他”）一起过一遍你的代码。

同样，当你在写APIDoc或任何其他文档的时候，同行的评审能帮助你的产出物更加清晰，因为你写的文档是让别人读的，你必须确保别人能理解你所作的东西。

同行的评审是一种非常不错的习惯，不仅仅是因为它能让代码变得更好，更重要的，在评审的过程中，评审人和代码作者通过分享和讨论，两人都能取长补短、相互促进。

如果你的团队只有你一个开发人员，找不出第二个人能给你作代码评审，这也没关系。你可以通过将你的代码片段开源，或吧有意思的代码片段贴在博客中，会有人对你的代码感兴趣的。

另外一个非常好的实践是使用版本管理工具（CVS，SVN或Git），一旦有人修改并提交了代码，都会发邮件通知组内成员。虽然大部分邮件都进入了垃圾箱，但总是会碰巧有人在工作间隙看到你所提交的代码，并对代码做出一些评价。