Android修炼系列（八），你真的会写注释吗？

Android

2023-10-16 15:38:06

在Android开发中，注释对于理解代码的含义和维护代码非常重要。优秀的注释可以帮助其他开发者和您自己快速理解代码的逻辑和实现细节。

Javadoc

Javadoc是一种用于生成Java API文档的工具。它可以从源代码中提取注释，并将其转换为HTML格式的文档。Javadoc注释使用一种特殊的语法，称为Javadoc标记(javadoc tag)。

javadoc标记以@符号开头，后面跟着标记的名称。标记的名称通常是动词或形容词，例如@param、@return、@throws等。

javadoc标记示例

以下是几个常用的javadoc标记示例：

@param：用于方法的参数。例如：

/**
 * 计算两个数的和。
 *
 * @param a 第一个数。
 * @param b 第二个数。
 * @return 两个数的和。
 */
public int sum(int a, int b) {
  return a + b;
}

@return：用于方法的返回值。例如：

/**
 * 计算两个数的和。
 *
 * @param a 第一个数。
 * @param b 第二个数。
 * @return 两个数的和。
 */
public int sum(int a, int b) {
  return a + b;
}

@throws：用于描述方法可能抛出的异常。例如：

/**
 * 计算两个数的和。
 *
 * @param a 第一个数。
 * @param b 第二个数。
 * @return 两个数的和。
 * @throws IllegalArgumentException 如果参数a或b为负数。
 */
public int sum(int a, int b) {
  if (a < 0 || b < 0) {
    throw new IllegalArgumentException("参数a或b为负数");
  }
  return a + b;
}