强制性方法文档

时间:2010-03-16 08:09:20

标签: language-agnostic documentation javadoc

在我以前的工作中,为javadoc提供所有方法是强制性的,这导致了如下所示:

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

正如您所看到的,文档占用空间和工作,但对代码几乎没有增加。

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

6 个答案:

答案 0 :(得分:3)

“使用javadoc提供所有方法是强制性的”

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

就我个人而言,我认为没有javadoc比完全无用的javadoc更好 - 至少你可以从一眼就看出哪些方法没有记录,因为没有参数的描述等。

文档经常被低估,因为在编写代码时它总是比在以后使用它时更不重要和紧迫。但是文档的风格和形式经常被高估 - 自动生成的XML废话仍然是无稽之谈。鉴于选择,我宁愿使用代码注释// Sets this object to use the specified frobber for all future frobbing,而不是零信息javadoc。

对于我从您的文档中知道的所有内容,该函数根本不会实际修改this对象,它可能会调用set()上的frobber函数,或者它可能是{{} 1}}因此它“设置了frobber”。我确定我读到某个地方“集合”是OED中具有最明确定义的单词。简要说明含糊不清,因此具有误导性,文档的目的是阻止人们依赖您的来源,从而阻止您当前实施的细节。我的评论实际上并没有比将“设置frobber”和“frobber”添加到IDE生成的javadoc存根所花费的时间更长。它没有解释什么是frobbing或什么时候这个对象(希望这是在类文档的其他地方),但至少它试图告诉你函数的作用。

至于何时授权文档 - 我认为必须记录每个接口。如果您没有定义Java while(!frobber.isset()) { refrigerator.add(frobber); sleep(3600); refrigerator.remove(frobber); },那么“接口”是每个公共和受保护的方法,以及每个受包保护的方法,除非包很小。实现不必记录,但如果它的工作方式不明显,则应对其进行评论。文档可能就像上面评论中的句子一样简单 - 如果方法描述已经说明了它们的内容,那么每个参数不一定需要单独的句子。

如果您有代码审核,那么IMO的答案是同时审核评论和文档。如果您没有代码审查,那么您需要cone of shame,以便最近迫使其他人过来并询问代码实际执行的内容。

这同样适用于依赖函数的未记录行为的任何人,结果是实现更改没有改变界面,打破了他们的代码。您强制执行该代码的方式是抱怨在您知道它要做什么之前不能调用它。像“javadoc评论必须存在”这样的任意规则变得不那么重要了,至少对于其他开发者需要调用的函数来说。

答案 1 :(得分:0)

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

答案 2 :(得分:0)

您应始终记录您的代码。特别是如果其他人工作或将处理您的代码。也许你还没有机会研究遗留下来的未记录的代码,但这可能是一个真正的痛苦!

关于评论本身,要避免的一件事是写评论,因为它是强制性的,只要想几秒钟,你就会找到一些东西来讲述你的方法,这些东西不在方法名称中,可能是对下一个开发者来说并不明显。解释你的方法做了什么,什么是极端情况,它期望作为输入。

请记住:

  

始终将代码视为最终的人   维护你的代码将是一个   暴力的精神病患者谁知道你在哪里   住。

它也适用于评论:)

答案 3 :(得分:0)

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

InfoQ有各种各样观点的最新摘要。

答案 4 :(得分:0)

代码文档非常重要。但Javadoc(或类似工具)不是唯一的,也不是最好的方法。最大的缺点是,Javadoc文档必须保持最新。如果方法发生了变化,但描述保持不变,那么这个文档可能会带来更多的麻烦。

为避免文档与代码不同步的问题,请使用代码进行记录。单元测试显示了代码的使用方式以及代码中的断言可以确保验证参数和返回值。在一个项目中,我将断言添加到计算中,此计算中的概率始终在0和1之间。稍后在用例中触发此断言并直接指向错误。

最重要的文档是一个很好的命名。如果你设置了Frobber,那么setFrobber就是一个好名字。您的示例中给出的Javadoc不会为此命名添加任何内容。 frobIt将是一个不太好的名字,method3将是非常糟糕的。代码审查应有助于获得良好的命名。

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

答案 5 :(得分:0)

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

答:强制性

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

答:所有

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

答:优点:聪明的人可以花时间专注于代码编写,而不是编写代码。代码很好地解释了。代码可以传递给新手。缺点:抱怨。陈旧的评论。

  • 关注质量评论可以避免“代码是自我记录”问题。

  • 对于getter和setter,并非每个get和set都是微不足道的。有时候,这很好。如果不是,评论应注意信息。最好是保守,总是有评论而非保守,不得不废弃代码,浪费时间搞清楚。

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