首页 › Java论坛 › Java学习笔记：注释

南笙北隐 發表於 2026-3-31 22:24:00

Java学习笔记：注释

<h3 id="1-什么是注释">1. 什么是注释？</h3>
<p>注释（comment）。对Java程序中的代码进行文字性解释说明。不会被Java编译和运行。</p>
<h3 id="2-java注释">2. Java注释</h3>
<p>Java中的注释主要分为三类：</p>
<table>
<thead>
<tr>
<th>类型</th>
<th>语法</th>
<th>用途</th>
</tr>
</thead>
<tbody>
<tr>
<td>单行注释</td>
<td>// 注释内容</td>
<td>对代码进行简短说明，编译时忽略</td>
</tr>
<tr>
<td>多行注释</td>
<td>/* 注释内容 */</td>
<td>可跨行，用于较长的解释或临时屏蔽代码块</td>
</tr>
<tr>
<td>文档注释</td>
<td>/** 注释内容 */</td>
<td>Java独有，用于生成API文档，可包含HTML标签和@标签</td>
</tr>
</tbody>
</table>
<h4 id="21-单行注释">2.1 单行注释</h4>
<pre><code class="language-java">//这是一个Java类
public class CommentTest {
        //main()方法：Java程序的主入口
        public static void main(String[] args) {
                System.out.println("Hello World!"); //这是一个打印输出语句
        }
}
</code></pre>
<h4 id="22-多行注释">2.2 多行注释</h4>
<pre><code class="language-java">/*
        这是一个多行注释
        可以在这里声明多行注释的信息！
        1. Java中有三种注释格式：单行注释、多行注释、文档注释（Java独有）
        2. 单行注释、多行注释的作用：
           ① 对程序中的代码进行解释说明。
           ② 可以注释可能存在错误的代码，方便程序进行调试。
      3. 注意：
           ① 单行注释和多行注释中声明的信息，不参与编译。即编译后生成的字节码文件中不包含注释内容。
           ② 多行注释不能嵌套使用。
*/
public class CommentTest {
        public static void main(String[] args)
        {
                System.out.println("Hello World!");
        }
}
</code></pre>
<p>查看源文件被编译后的字节码文件中，单行注释和多行注释是否被编译：</p>
<p><img src="https://img2024.cnblogs.com/blog/3382744/202603/3382744-20260331201044075-503856025.png"></p>
<ul>
<li>如图所示，注释没有被Java编译器进行编译。</li>
</ul>
<h4 id="23-文档注释">2.3 文档注释</h4>
<p>Java独有。文档注释内容可以被JDK提供的文档生成工具（javadoc）解析，生成一套以网页文件（HTML）形式体现的该程序的说明文档。</p>
<p><strong>1. 文档注释常用标签</strong></p>
<table>
<thead>
<tr>
<th>标签</th>
<th>描述</th>
<th>适用位置</th>
</tr>
</thead>
<tbody>
<tr>
<td>@author</td>
<td>作者</td>
<td>类、接口</td>
</tr>
<tr>
<td>@version</td>
<td>版本</td>
<td>类、接口</td>
</tr>
<tr>
<td>@param</td>
<td>参数说明</td>
<td>方法、构造器</td>
</tr>
<tr>
<td>@return</td>
<td>返回值说明</td>
<td>方法</td>
</tr>
<tr>
<td>@throws / @exception</td>
<td>抛出的异常</td>
<td>方法、构造器</td>
</tr>
<tr>
<td>@see</td>
<td>参考链接</td>
<td>任意</td>
</tr>
<tr>
<td>@since</td>
<td>从哪个版本开始</td>
<td>类、方法、字段</td>
</tr>
<tr>
<td>@deprecated</td>
<td>已过时</td>
<td>类、方法、字段</td>
</tr>
</tbody>
</table>
<p><strong>2. javadoc 工具的使用</strong></p>
<p>示例使用的源文件<code>CommentTest.java</code>，内容：</p>
<pre><code class="language-java">/**
文档注释：
文档注释内容可以被JDK提供的javadoc工具解析，生成一套以网页文件形式体现的该程序的说明文档。

@author Evan
@version 1.0
*/
public class CommentTest {
        public static void main(String[] args) {
                System.out.println("Hello World!");
        }
}
</code></pre>
<p><strong>基本命令格式:</strong></p>
<pre><code class="language-bash">javadoc [选项] [包名] [源文件名]
</code></pre>
<p><strong>常用选项</strong></p>
<table>
<thead>
<tr>
<th>选项</th>
<th>说明</th>
</tr>
</thead>
<tbody>
<tr>
<td>-d &lt;目录&gt;</td>
<td>指定生成的HTML文档存放目录</td>
</tr>
<tr>
<td>-author</td>
<td>包含@author信息</td>
</tr>
<tr>
<td>-version</td>
<td>包含@version信息</td>
</tr>
<tr>
<td>-encoding</td>
<td>源文件编码，如<code>UTF-8</code></td>
</tr>
<tr>
<td>-charset</td>
<td>生成的HTML文档字符集</td>
</tr>
<tr>
<td>-private</td>
<td>显示所有类和成员（默认只显示public和protected）</td>
</tr>
</tbody>
</table>
<p><strong>示例1:</strong> 为源文件生成HTML文档</p>
<ol>
<li>
<p>打开cmd命令行终端，切换到源文件所在目录。</p>
</li>
<li>
<p>执行命令：</p>
<pre><code class="language-bash">javadoc -d mydoc -encoding gbk -charset gbk -version -author CommentTest.java
</code></pre>
<p><img src="https://img2024.cnblogs.com/blog/3382744/202603/3382744-20260331201642134-724540260.png"></p>
<ul>
<li><code>-d mydoc</code>：将生成的文档放到<code>mydoc</code>目录下。</li>
<li><code>-author -version</code>：在文档中显示作者和版本信息。</li>
<li><code>-encoding gbk -charset gbk</code>：指定源文件的字符编码和生成后HTML文件的字符编码。
<ul>
<li>-charset utf-8 指定生成的 HTML 文档的字符集。</li>
<li><strong>忽略编码参数</strong>：<br>
如果不指定 <code>-encoding</code> 时，<code>javadoc</code>会使用系统默认字符编码（Windows 上通常是 GBK，Linux/macOS 是 UTF-8），这样可能在跨平台时出现乱码，因此不推荐。</li>
</ul>
</li>
</ul>
</li>
<li>
<p>在<code>../mydoc/index.html</code> 即可查看生成的API文档。</p>
</li>
</ol>
<p><strong>示例2：</strong> 为整个包生成HTML文档</p>
<pre><code class="language-bash">javadoc -d mydoc -author -version com.example.utils
</code></pre>
<h3 id="3-常见问题">3. 常见问题</h3>
<ol>
<li>
<p>使用 <code>javadoc -encoding utf-8</code> ，出现错误: <strong>编码utf-8的不可映射字符</strong></p>
<ul>
<li>
<p><strong>原因分析</strong><br>
这个错误通常是因为 源文件的实际编码 与 -encoding 指定的编码不一致导致的。javadoc 尝试用 UTF-8 读取文件，但源文件中存在不符合 UTF-8 格式的字节（比如用 GBK 保存的中文字符），于是报“不可映射字符”。</p>
</li>
<li>
<p><strong>解决方案</strong><br>
确认源文件的真实编码：</p>
<ul>
<li>方式1：用记事本打开源文件，点击“另存为”，查看右下角的编码。</li>
<li>方式2：在 Windows 上打开cmd命令行，使用 <code>chcp</code>命令 查看活动代码页。</li>
</ul>
<p>根据实际编码调整 <code>-encoding</code> 参数，如果源文件是 GBK 编码，将命令改为：</p>
<pre><code class="language-bash">javadoc -d mydoc -encoding gbk -charset utf-8 CommentTest.java
</code></pre>
<ul>
<li>如果源文件是 UTF-8，但可能带有 BOM，也可以继续用 -encoding utf-8，但建议确保文件是无 BOM 的 UTF-8。</li>
</ul>
</li>
<li>
<p><strong>将源文件统一转为 UTF-8（推荐）</strong><br>
用文本编辑器（如 VS Code、Notepad++）将源文件另存为 UTF-8 无 BOM 格式。<br>
之后就可以放心使用：</p>
<pre><code class="language-bash">javadoc -encoding utf-8 -charset utf-8 CommentTest.java
</code></pre>
</li>
</ul>
</li>
<li>
<p>文档注释中的内容可以包含HTML标签（如<code>&lt;p&gt;</code>、<code>&lt;code&gt;</code>）来格式化文本。</p>
</li>
<li>
<p>若注释中包含{@code ...}或{@literal ...}，可避免HTML转义，直接显示代码片段。</p>
</li>
<li>
<p>良好的文档注释应清晰描述功能、参数、返回值及异常，便于他人使用和维护。</p>
</li>
</ol><br><br>
来源：https://www.cnblogs.com/lisong0626/p/19803467

查看完整版本: Java学习笔记：注释