对于需要长期维护的代码，为了使之后阅读代码能够理解其内容，添加适当的注释是很重要的。不过，虽然说是「适当的注释」，但书写合适的注释本身就不是一件容易的事。
这时，标准就是按照文档注释的规则来写注释。文档注释是指在类或者其成员的前面按照一定的规则来描述其功能的注释。使用称为JSDoc的工具，可以自动获取必要的信息并自动生成API文档（规格书）。
右图是使用JSDoc自动生成的规格书的例子。
管理成员信息
姓
名
显示成员的详细信息
请改用Member#toString方法
成员的姓名
将Member类的内容转为字符串
成员的姓名
●使用JSDoc自动生成的文档
文档注释是在源代码中管理的，所以有以下优点。
- 配合源代码的修改，可以使维护更加容易
- 减少源代码和文档间的矛盾
即使源代码中发生了变更，也只要执行一个命令就可以将文档更新到最新的状态。