我想尽可能缩短内联评论,因为我的经验是超过3或4行的评论往往被掩盖,创造了许多不必要的"阅读手册".
遗产要求我遵守与jsdoc兼容的格式来记录代码.如果要正确记录,则需要明确声明许多不言而喻的事情.实际上每个标签都属于这一类.即使是那些不工作的人对于工作的开发人员来说通常也是无用的.
我的愿景是在开发人员实际阅读的代码本身内部进行快速摘要,但是引用一个单独的文件(甚至是同一文件中的注释转储,与开发人员工作的地方分开)以进行其他标记,如下所示:
/**
* Used when making an example of the argument.
* @include someotherplace
*/
function example(argument) { stuff;}
...lots more code...
/**
* someotherplace
* @param argument The victim
* @since forever
* @other stuff
*/
一个不同的工具或插件是可以接受的,我真的只是坚持语法.另一个替代方案是一个具有一些非常好的隐式文档创建的工具