《Java 核心技术卷1》笔记第四章：类与对象(7) 注释、JavaDoc与类设计

钰娘娘

已于 2022-01-22 16:39:50 修改

阅读量595

点赞数

分类专栏： java 《Java 核心技术卷1》文章标签： java 开发语言后端

于 2022-01-21 14:08:01 首次发布

本文链接：https://blog.csdn.net/yu_duan_hun/article/details/122617473

版权

《Java 核心技术卷1》同时被 2 个专栏收录

123 篇文章 21 订阅

订阅专栏

java

83 篇文章 2 订阅

订阅专栏

4.9 文档注释

javadoc可以自动将程序中的注释生成文档，可以通过重新生成得到最新的注释内容

4.9.1 注释的插入

javadoc注释的特性：

包
公有类与接口
公有和受保护的方法
公有和受保护的全局变量

书写方法：

可以加标记，使用@字符，例如@author或@param
第一句是概要，javadoc会把它抽取出来
可用HTML标记，如<em></em>
内容图片等，可以通过子目录的doc-files目录实现

如图，选择 Tools->Generate JavaDoc

测试程序：

public class Main {

    public static  void main(String[] args){

        Main solution = new Main();

        solution.test2(3,5);

    }



    public void test(){



    }



    /**

     * 输出a和b的值

     * @param a 参数1

     * @param b 参数2         

     * @return 10的<strong>数值  </strong>

     */

    public int test2(int a, int b){

        System.out.println(a);

        System.out.println(b);

       return 10;

    }

}

Command: -encoding utf-8 -charset utf-8

点击左侧的 Main，查看效果：

类常用标记：

@author 作者

@version 版本号

@since java开始支持版本

方法常用标记：

@param 参数名

@return 返回值

@throws 抛出异常

可参考现有源码的书写，例如System.out.printf 的注释内容

javadoc文档地址（原链接失效，自己找了一个）：https://www.oracle.com/java/technologies/javase/javadoc-tool.html

4.10 类设计技巧

（1）类内的全局变量设计为私有。访问使用accessor(访问器)，修改使用mutator(修改器)。事实上大家对这一点也有不同的看法。因为使用访问器和修改器，以及使用访问修饰符，Java的代码显得冗长又啰嗦，这也是Java一直被诟病的原因之一。基于安全，这种设计是绝对正确的。

（2）全局变量要初始化。作者认为，全局变量需要进行初始化。个人认为持怀疑态度。经典范例是懒加载。对于大对象，我们希望在没有使用的情况下，尽量不要进行实例化，以此达到节约内存，加快处理速度的目的。

（3）不要再类中使用过多的基本数据类型。这个非常对，尤其是对接外部的请求和响应，最好不要使用基本类型，否则在对方使用不同语言编码的时候，容易因为数据类型原因，导致数据根本接不进来。平时用到基本类型的地方是，索引遍历，数值格式检查，数据由一条按数量拆分成多条等等。

（4）不是所有的全局变量都需要独立的访问器和修改器。比如有些数值无需外部访问，只需内部调用。经典案例：String 类型，内部的 char 数组不提供对外的访问器和修改器。

（5）按照特定格式书写类的定义。这个不强调，因为看了下源码，也不遵从这个规则。目前我这边规则是先变量再方法，其他按照实际需要书写，同名的重载构造器或者方法最好写在一起。

（6）将职责过多的类进行分解。如果一个类职责过多，应把它分解成小块。事实就是大家都这么想（理想状态），但是很少有人有资格去做。因为重构代码是有可能产生新bug的，这个责任需要有人承担，技术总监大多情况不会允许你进行重构。通常只在业务扩展，现有代码不满足业务需求的情况进行重构。如果代码中有比较多的地方进行重构，宁可从头写，也不进行部分重构。

（7）类名和方法名要有意义，体现用途。比如 Shop 代表商店，Product 代表产品，PaymentWay 代表支付方式，一目了然。好的名字可以快速了解类的用途，从而加快开发处理速度。

系列内容：

《Java 核心技术卷1》笔记：第一章 Java程序设计概述

《Java 核心技术卷1》笔记：第二章 Java程序设计环境

《Java 核心技术卷1》笔记：第三章 Java基本的程序设计结构（1）

《Java 核心技术卷1》笔记：第三章 Java基本的程序设计结构（2）

《Java 核心技术卷1》笔记：第三章 Java基本的程序设计结构（3）

《Java 核心技术卷1》笔记：第三章 Java基本的程序设计结构（4）

《Java 核心技术卷1》笔记：第三章 Java基本的程序设计结构（5）

《Java 核心技术卷1》笔记：第三章 Java基本的程序设计结构（6）

《Java 核心技术卷1》笔记：第三章 Java基本的程序设计结构（7）大数处理、数组、多维数组、控制台传参

《Java 核心技术卷1》笔记第四章：类与对象