代码之家 › 专栏 › 技术社区 › Sjoerd

强制性方法文件[关闭]

javadoc documentation language-agnostic

Sjoerd · 技术社区 · 14 年前

在我之前的工作中,向所有方法提供JavaDoc是强制性的,这导致了以下情况:

/**
 * Sets the Frobber.
 *
 * @param frobber The frobber
 */
public setFrobber(Frobber frobber) { ... }

如您所见,文档占用了空间和工作,但对代码几乎没有添加什么。

记录所有方法是强制性的还是可选的?是否有记录哪些方法的规则?要求记录每种方法的利弊是什么?

6 回复 | 直到 14 年前

Steve Jessop 14 年前

“必须为所有方法提供JavaDoc”

我强烈怀疑记录所有方法是强制性的,但是提供JavaDoc注释是可以自动强制执行的,因此所有这些都是统一完成的。

我个人认为没有javadoc比完全无用的javadoc更好——至少你可以从HTML的一瞥中看到哪些方法是未记录的,因为没有对参数的描述等等。

文档经常被低估,因为在编写代码时,它总是比稍后使用时更不重要和紧迫。但是文档的样式和形式常常被高估——自动生成的XML胡说八道仍然是胡说八道。如果可以选择,我宁愿让代码注释 // Sets this object to use the specified frobber for all future frobbing 而不是你的零信息javadoc。

据我从你的文档中所知,这个函数实际上没有修改 this 对象,它可能调用 set() 作用于 frobber 或者可能是 while(!frobber.isset()) { refrigerator.add(frobber); sleep(3600); refrigerator.remove(frobber); } 因此,它“使人发笑”。我肯定在某个地方读到过“set”这个词,它在《牛津英语词典》中有着最清晰的定义。简短的描述是模棱两可的,因此具有误导性,文档的目的是阻止人们依赖您的源代码,从而阻止人们依赖您当前实现的细节。我的评论写起来并不比在IDE生成的javadoc存根中添加“set the frober”和“the frober”花费的时间长。它没有解释什么是泡沫,什么时候这个对象会泡沫(希望在类文档的其他地方),但至少它试图告诉你这个函数的作用。

至于什么时候授权文件——我认为界面必须记录在案。如果你没有定义Java interface s,“接口”是所有公共的和受保护的方法,以及每个包保护的方法,除非包很小。不必记录实现,尽管如果它的工作方式不明显,应该对其进行注释。文档可能和上面我的注释中的句子一样简单——如果方法描述已经说明了每个参数的含义,那么您不必为每个参数单独使用一个句子。

如果你有代码审查,那么IMO的答案是同时审查评论和文档。如果没有代码检查,则需要 cone of shame 对于最近迫使其他人过来询问代码实际做了什么的开发人员来说。

同样的情况也适用于任何依赖于函数的未记录行为的人,结果是实现的改变没有改变接口,从而破坏了他们的代码。强制代码被记录下来的方法是抱怨在知道它保证要做什么之前不能调用它。“JavaDoc注释必须存在”之类的任意规则变得不那么重要,至少对于其他开发人员需要调用的函数而言。

Sarfraz 14 年前

为了大的您正在创建的项目或框架/库,甚至是开源项目,都是必需的。对于小型个人或私人项目,这是可选的。尽管如此,记录代码始终是一个好主意,因此如果您在一年后回到项目中,无论大小,您都知道它在做什么。这真的很有帮助。

f4. 14 年前

您应该始终记录您的代码。尤其是当其他人在你的代码上工作或将要工作的时候。也许您还没有机会处理遗留的没有文档记录的代码,但这可能是一个真正的痛苦!

关于注释本身,有一件事要避免,那就是写注释,因为它是强制性的,只要思考几秒钟,你就会发现一些关于你的方法的信息,一些还没有出现在方法名中的信息,一些对下一个开发人员来说可能不明显的信息。解释你的方法做了什么,角落案例是什么,它期望输入什么。

记住:

总是把代码编码成维护您的代码将是知道你在哪里的暴力精神病患者现场直播。

它也适用于注释:)

John 14 年前

维护“自记录”代码要容易得多。如果选择好的函数和变量名,请保持函数简短(例如,每个函数只有一个想法的10行),这将有助于保持代码的目的清晰。而且你不必试图保持评论的最新-唯一比没有评论更糟糕的是评论是错误的!

有一个好的和最近的各种观点的总结在 InfoQ .

Mnementh 14 年前

代码文档非常重要。但JavaDoc(或类似的工具)并不是实现这一点的唯一方法,也不是最佳方法。最大的缺点是,JavaDoc文档必须保持最新。如果更改了方法,但描述保持不变,则此文档可能会带来更多的麻烦。

要避免文档与代码不同步的问题,请使用代码到文档。单元测试显示如何使用代码,代码中的断言可以确保参数和返回值得到验证。在一个项目中,我向一个计算添加了断言,这个计算中的概率总是在0和1之间。稍后,这个断言在用例中触发,并将我直接指向一个bug。

最重要的文档是一个好的命名。如果你设置一个泡沫,那么泡沫是一个好名字。在您的示例中给出的javadoc没有为这个命名添加任何内容。frobit是一个不太好的名字,方法3将非常糟糕。代码评审应该有助于获得良好的命名。

如果其他方法不够,则应添加javadocs和ither文档。但在这种情况下,您需要注意,这个文档总是最新的。

Paul Nathan 14 年前

问:记录所有方法是强制性的还是可选的?

答: 强制性的 .

问:有没有规定哪些方法需要记录?

答: 所有这些 .

问:要求记录每种方法的利弊是什么?

答:优点:聪明人可以把时间花在写代码上,而不是花在找出代码上。代码解释得很好。代码可以传递给新手。欺骗: 哀鸣 . 陈旧的评论

关注质量评论可以避免“代码是自记录”的问题。
对于getter和setter,并不是每个get和set都是微不足道的。有时候是的,太好了。如果不是,评论应该注意信息。保守和总是有评论总比不保守要好,必须废弃代码,浪费时间去弄清楚。

最后一个例子: Carmack Inverse Square Root code. 自我记录,嗯?