如何记录(简单)Java方法的前提条件? [英] How to document (simple) preconditions of a Java method?

问题描述

通常情况下，方法对其类型的参数施加约束，而类型系统无法描述这些约束.例如，一种方法可能要求某些参数为非空，或某些int类型的参数为正.可能还存在更复杂的前提条件，例如，之前调用过某种方法，或者某个对象处于某种状态.用Javadoc记录此内容的最佳方法是什么?

It is often the case that a method imposes constraints on its arguments that cannot be described by the type system. For example, a method might require that some argument be non-null, or some int-typed argument be positive. There might also be more complex preconditions, for example that a certain method was called before, or that a certain object is in some state. What is the best way to document this in Javadoc?

例如，假设我具有以下公共库函数，其中参数不能为负:

For example, suppose I have the following public library function, where the argument cannot be negative:

public void foo(int bar) {
    if (bar < 0) {
        throw new IllegalArgumentException("Negative bars cannot be food.");
    }
    ...
} 

我想以此方式记录该文档，使其在其余文档文本中脱颖而出"，以便文档读者立即知道他们必须看的地方.目前，我是通过在Javadoc中添加throws子句来做到这一点的:

I want to document this in such a way that it "stands out" from the rest of the documentation text so that documentation readers know immediately where they have to look. Currently, I do this by adding throws clauses to the Javadoc:

/**
 * Foos a bar.
 * @param bar  the bar to be food
 * @throws IllegalArgumentException  if bar is negative
 */
public void foo(int bar) {
    ...

但是，这将异常的抛出引入了方法的规范中.现在，库用户可能依赖于其代码中的此行为.因此，如果我想以允许负参数的方式在下一版本中更改方法，则可能会破坏客户的代码.

However, this introduces the throwing of the exception into the specification of the method. Now, library users might depend on this behavior in their code. So if I want to change the method in a next version in such a way that also negative parameters are allowed, I might break clients' code.

是否有最佳实践来用Javadoc记录这样的事情?我想到了:

Are there any best practices to document things like this in Javadoc? I have thought of:

• 在文档文本中描述，如果参数为负，则该方法具有未定义的行为.但是，这并没有真正脱颖而出，因此很多图书馆用户可能会忽略它.
• 使用注释(public void foo(@NonNegative int bar)).但是，为此，标准的注释集将是理想的，并且该标准集似乎不存在.

• Describing in the documentation text that the method has undefined behavior if the argument is negative. However, this does not really stand out, so it might be missed by a lot of library users.
• Using annotations (public void foo(@NonNegative int bar)). However, for this a standard set of annotations would be ideal, and this standard set does not appear to exist.

推荐答案

您似乎不愿意依靠API的Javadocs来提供确切的信息:API文档.虽然我同意一些开发人员总是会忽略其警告，但我认为从历史上看Javadocs在提供有关如何正确使用API​​的充分指导方面是完全足够的.您可能会疯狂地创建各种自定义Annotation，但是最终人们仍然有时会错误地实现您的API.

You seem hesitant to rely on your API's Javadocs to provide exactly that: documentation for your API. While I agree some developers will invariably ignore its warnings, I think historically Javadocs have been entirely adequate in providing sufficient guidance on how to correctly use an API. You can go crazy creating all kinds of custom Annotations, but in the end people will still implement your API incorrectly at times.

如果您想进一步超越现有功能，还可以实现 self -documenting 命名约定(如果可行).例如:

If you did want to go even further beyond what you already have there, you could also implement self-documenting naming conventions wherever practical. For example:

/**
 * Foos a positive bar.
 * @param positiveBar  the non-zero,non-negative bar to be food
 * @throws IllegalArgumentException  if bar is zero or negative
 */
public void foo(int positiveBar) {
    ...

最后，尽管您的问题是关于如何记录这些约束而不是如何处理它们，但我会说不要低估IllegalArgumentException的值.这恰好是它的用途，工程师不应该害怕抛出此异常来表示编程错误.如果开发人员的实现无法运行，那么开发人员将无法不阅读文档.

Lastly, although your question is about how to document these constraints and not handle them, I will say to not underestimate the value of IllegalArgumentException. This is precisely what it should be used for and engineers should not be afraid to throw this exception to indicate a programming error. Developers aren't going to get far without reading the docs when their implementation doesn't run.

这篇关于如何记录(简单)Java方法的前提条件?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！