方法文件

Question

我想知道记录以下简化有理数的方法的最佳实践。

/**
 * Simplifies a rational number
 * 
 * @return  ...
 *          | result == new Rational(this.getNumerator() / gcd, this.getDenominator()/ gcd);
 */
public Rational simplify() {
    long gcd = ExtMath.gcd(Math.abs(this.getNumerator()),
            Math.abs(this.getDenominator()));
    if (this.getDenominator() < 0)
        gcd *= -1;
    return new Rational(this.getNumerator() / gcd, this.getDenominator()
            / gcd);
}

Answer 1

Javadoc应该从一个相对较短的句子开始，说明该方法的作用。 （这句话被提取到课程文档的方法摘要中。）然后，如果需要，可以详细说明。但是，您不应该描述方法的内部操作，除非这对于了解如何编写客户端代码以使用该方法很重要。 Javadoc还应包含一个记录返回值的@return标记。

假设该方法是Rational类的一部分，我可能会这样写：

/**
 * Returns a new {@code Rational} that represents this {@code Rational} in reduced
 * form. The denominator of the returned value will be non-negative.
 *
 * @return a new {@code Rational} that represents this {@code Rational}
 *         in reduced form.
 */

如果可能针对Rational的特殊值（例如，零分母）抛出异常，那么我可能会添加@throws标记记录什么时候会发生。

如果此方法与其他内容密切相关，我可能还会添加一个或多个@see代码。

P.S。像@pre，@post等标签是自定义标签（请参阅the docs here）。有很多关于如何使用这些指南的指南（例如，请参阅here），但我不知道任何＆＃34;最佳做法＆＃34;除了要清楚。