/ **和/ *在Java中的注释 [英] /** and /* in Java Comments

问题描述

/**
 * comment
 *
 *
 */

和

/*
 * 
 * comment
 *
 */

在Java？我应该何时使用它们？

in Java? When should I use them?

推荐答案

第一种形式称为 Javadoc 。当你为你的代码编写正式的API时，你会使用它，这是由 javadoc 工具生成的。例如， Java 7 API页面使用Javadoc并由该工具生成。

The first form is called Javadoc. You use this when you're writing formal APIs for your code, which are generated by the javadoc tool. For an example, the Java 7 API page uses Javadoc and was generated by that tool.

您在Javadoc中看到的一些常见元素包括：

Some common elements you'd see in Javadoc include:

• @param ：用于表示传递给方法的参数以及它们应该具有的值

• @param: this is used to indicate what parameters are being passed to a method, and what value they're expected to have

@return ：用于表示方法将返回的结果

@return: this is used to indicate what result the method is going to give back

@throws ：这用于表示某个方法在某些输入的情况下抛出异常或错误

@throws: this is used to indicate that a method throws an exception or error in case of certain input

@since ：这用于表示

例如，下面是比较方法的方法的Javadoc Integer ：

As an example, here's Javadoc for the compare method of Integer:

/**
 * Compares two {@code int} values numerically.
 * The value returned is identical to what would be returned by:
 * <pre>
 *    Integer.valueOf(x).compareTo(Integer.valueOf(y))
 * </pre>
 *
 * @param  x the first {@code int} to compare
 * @param  y the second {@code int} to compare
 * @return the value {@code 0} if {@code x == y};
 *         a value less than {@code 0} if {@code x < y}; and
 *         a value greater than {@code 0} if {@code x > y}
 * @since 1.7
 */
public static int compare(int x, int y) {
    return (x < y) ? -1 : ((x == y) ? 0 : 1);
}

第二种形式是块（多行）注释。

The second form is a block (multi-line) comment. You use this if you want to have multiple lines in a comment.

我会说你只想谨慎使用后一种形式 >;也就是说，你不希望使用块注释覆盖你的代码，而这些注释没有描述方法/复杂函数应该具有的行为。

I will say that you'd only want to use the latter form sparingly; that is, you don't want to overburden your code with block comments that don't describe what behaviors the method/complex function is supposed to have.

由于Javadoc是更具描述性的两个，你可以生成实际文档作为使用它的结果，使用Javadoc将更喜欢简单块注释。

Since Javadoc is the more descriptive of the two, and you can generate actual documentation as a result of using it, using Javadoc would be more preferable to simple block comments.

这篇关于/ **和/ *在Java中的注释的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！