JAVA学习 DAY3 注释与编码规范讲解

 本系列可作为JAVA学习系列的笔记，文中提到的一些练习的代码，小编会将代码复制下来，大家复制下来就可以练习了，方便大家学习。

点赞关注不迷路！您的点赞、关注和收藏是对小编最大的支持和鼓励！ 

---

 系列文章目录

JAVA学习 DAY1 初识JAVA

JAVA学习 DAY2 java程序运行、注意事项、转义字符

JAVA学习 DAY3 注释与编码规范讲解

---

目录

 系列文章目录

前言

一、注释

1.Java中的注释

1. 单行注释

2. 多行注释

3. 文档注释 (Javadoc)

1.命令参数解释

4.javadoc 标签

2.注释的最佳实践

二、Java代码注释与编码规范详解

1. 类、方法的注释，要以javadoc的方式来写

2. 非Java Doc的注释

3. 代码缩进规范

4. 运算符和=的空格规范

5. 源文件编码

6. 行宽度限制

7. 代码编写风格（次行风格和行尾风格）

行尾风格（推荐）

次行风格

8.总结

三、总结

---

前言

小编作为新晋码农一枚，会定期整理一些写的比较好的代码，作为自己的学习笔记，会试着做一下批注和补充，如转载或者参考他人文献会标明出处，非商用，如有侵权会删改！欢迎大家斧正和讨论！

本系列文章可以作为学习JAVA的笔记使用，本文除了小编的笔记，还整理了 宝藏老师 B站up主：韩顺平  的系列视频笔记：【零基础 快速学Java】韩顺平 零基础30天学会Java

一、注释

1.Java中的注释

注释是Java代码中重要的组成部分，它可以帮助开发者理解代码的功能、逻辑和意图。Java支持三种类型的注释：

1. 单行注释

单行注释以//开头，直到行尾结束。它通常用于对单行代码进行解释或临时禁用某行代码。

// 这是一个单行注释
int x = 10; // 也可以跟在代码后面// System.out.println("这行代码被注释掉了");

2. 多行注释

多行注释以/*开头，以*/结尾，可以跨越多行。适用于对较长的代码块或复杂逻辑进行解释。

/** 这是一个多行注释* 可以包含多行文本* 常用于方法或复杂逻辑的说明*/
public void myMethod() {/** 这里的代码被注释掉了* int a = 1;* int b = 2;* System.out.println(a + b);*/
}

3. 文档注释 (Javadoc)

文档注释以/**开头，以*/结尾，是专门用于生成API文档的注释格式。Javadoc工具可以解析这些注释并生成一套以网页文件形式体现的该程序的说明文档，一般写在类

/*** 计算器类，提供基本的加减乘除运算* * @author Example Author* @version 1.0*/
public class SimpleCalculator {/*** 两个数相加* @param a 第一个数* @param b 第二个数* @return 两数之和*/public int add(int a, int b) {return a + b;}/*** 两个数相减* @param a 被减数* @param b 减数* @return 两数之差*/public int subtract(int a, int b) {return a - b;}
}

javadoc -d 文件夹名 -xx -yy Demo3.java 

-xx和-yy是包含的标签，需要写出来。

执行如下指令：

javadoc -d F:\javacode1\test -author -version -parameters SimpleCalculator.java

1.命令参数解释

1. -d F:\javacode1\test：指定输出目录为F:\javacode1\test
2. -author：在生成的文档中包含@author信息
3. -version：在生成的文档中包含@version信息
4. -parameters：在生成的文档中包含方法参数的信息
5. -param vs -parameters：正确的选项是-parameters（复数形式），而不是-param
6. -return：Javadoc工具没有-return选项。返回值信息会自动包含在方法文档中，只要你在注释中使用了@return标签

但是此时观察到，我们运行的结果显示报错：

​ parameters无效，这是因为JDK版本，使用的是JDK 7或更早版本，-parameters选项将不可用。

如果你无法升级JDK，可以省略-parameters选项： 

javadoc -d F:\javacode1\test -author -version SimpleCalculator.java

​

 查看指定的输出目录F:\javacode1\test

​

点击index.html  ，可以看到文件

​

4.javadoc 标签

javadoc 工具软件识别以下标签：

标签	描述	示例
@author	标识一个类的作者	@author description
@deprecated	指名一个过期的类或成员	@deprecated description
{@docRoot}	指明当前文档根目录的路径	Directory Path
@exception	标志一个类抛出的异常	@exception exception-name explanation
{@inheritDoc}	从直接父类继承的注释	Inherits a comment from the immediate surperclass.
{@link}	插入一个到另一个主题的链接	{@link name text}
{@linkplain}	插入一个到另一个主题的链接，但是该链接显示纯文本字体	Inserts an in-line link to another topic.
@param	说明一个方法的参数	@param parameter-name explanation
@return	说明返回值类型	@return explanation
@see	指定一个到另一个主题的链接	@see anchor
@serial	说明一个序列化属性	@serial description
@serialData	说明通过writeObject( ) 和 writeExternal( )方法写的数据	@serialData description
@serialField	说明一个ObjectStreamField组件	@serialField name type description
@since	标记当引入一个特定的变化时	@since release
@throws	和 @exception标签一样.	The @throws tag has the same meaning as the @exception tag.
{@value}	显示常量的值，该常量必须是static属性。	Displays the value of a constant, which must be a static field.
@version	指定类的版本	@version info

2.注释的最佳实践

1. 解释为什么而不是做什么：代码本身应该清楚地表达它在做什么，注释应该解释为什么这样做。

2. 保持注释更新：当代码修改时，相关的注释也应该更新。

3. 避免冗余注释：不要写明显从代码中就能看出来的注释。

4. 使用Javadoc记录公共API：对于公共类、接口和方法，应该使用Javadoc进行详细记录。

5. 谨慎使用注释掉的代码：如果代码被注释掉，最好直接删除，或者使用版本控制系统来跟踪历史记录。

6. 注释复杂逻辑：对于复杂的算法或业务逻辑，注释可以帮助其他开发者理解。

7. 被注释的文字，不会被JVM（JAVA虚拟机）解释执行。

8. 多行注释里面不允许有多行注释嵌套。

良好的注释习惯可以大大提高代码的可维护性和可读性，特别是在团队协作开发中。

二、Java代码注释与编码规范详解

图中展示了Java代码注释和编码规范的详细要求，我将逐条进行讲解：

1. 类、方法的注释，要以javadoc的方式来写

• Javadoc是Java官方文档注释格式，使用/** ... */包裹
• 用于生成API文档，包含类、方法的功能描述、参数说明、返回值说明等
• 示例：

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

2. 非Java Doc的注释

• 这类注释是给代码维护者看的，主要说明：
  • 为什么这样写（设计思路）
  • 如何修改（扩展建议）
  • 注意事项（潜在问题）
• 示例：

  // 使用单例模式确保全局只有一个实例（设计思路）
  // 如需扩展多实例，可修改getInstance方法（修改建议）
  // 注意线程安全问题（注意事项）

3. 代码缩进规范

• 使用Tab操作进行缩进
• 默认整体向右移动（按Tab键）
• 需要向左移动时，使用Shift+Tab组合键

4. 运算符和=的空格规范

• 运算符两边各加一个空格，提高可读性
• 示例：
  • 正确：2 + 4 * 5 + 345 - 89
  • 错误：2+4*5+345-89

5. 源文件编码

• 使用UTF-8编码，这是最通用的字符编码标准
• 确保文件保存时选择UTF-8编码，避免中文乱码问题

6. 行宽度限制

• 每行代码不超过80字符
• 超过时应换行，保持代码整洁

7. 代码编写风格（次行风格和行尾风格）

图中展示了两种条件判断的代码风格对比：

行尾风格（推荐）

public ArrayList(int initialCapacity) {if (initialCapacity > 0) {this.elementData = new Object[initialCapacity];} else if (initialCapacity == 0) {this.elementData = EMPTY_ELEMENTDATA;} else {throw new IllegalArgumentException("Illegal Capacity: "+initialCapacity);}
}

• 特点：else或异常抛出语句与前面的}在同一行
• 优点：减少行数，结构紧凑

次行风格

public ArrayList(int initialCapacity) {if (initialCapacity > 0){this.elementData = new Object[initialCapacity];} else if (initialCapacity == 0){this.elementData = EMPTY_ELEMENTDATA;} else{throw new IllegalArgumentException("Illegal Capacity: "+initialCapacity);}
}

• 特点：{单独占一行
• 优点：某些团队认为更清晰，但占用更多行数

8.总结

这些规范旨在：

1. 提高代码可读性和可维护性
2. 确保团队协作时风格统一
3. 便于生成专业的API文档
4. 遵循行业最佳实践

建议团队在项目开始时确定一套统一的编码规范，并通过代码审查确保规范得到遵守。

---

三、总结

以上就是今天要讲的内容，本文简单记录了java学习内容，仅作为一份简单的笔记使用，大家根据注释理解，您的点赞关注收藏就是对小编最大的鼓励！