阿里Java编程规约【九】 注释规约

简介: 1.【强制】类、类属性、类方法的注释必须使用 Javadoc 规范,使用 /** 内容 */ 格式,不得使用 // xxx 方式。说明:在 IDE 编辑窗口中,Javadoc 方式会提示相关注释,生成 Javadoc 可以正确输出相应注释;在 IDE 中,工程调用方法时,不进入方法即可悬浮提示方法、参数、返回值的意义,提高阅读效率。

1.【强制】类、类属性、类方法的注释必须使用 Javadoc 规范,使用 /** 内容 */ 格式,不得使用 // xxx 方式。


说明:在 IDE 编辑窗口中,Javadoc 方式会提示相关注释,生成 Javadoc 可以正确输出相应注释;在 IDE 中,工程调用方法时,不进入方法即可悬浮提示方法、参数、返回值的意义,提高阅读效率。


2.【强制】所有的抽象方法(包括接口中的方法)必须要用 Javadoc 注释、除了返回值、参数异常说明外,还必须指出该方法做什么事情,实现什么功能。


说明:对子类的实现要求,或者调用注意事项,请一并说明。


3.【强制】所有的类都必须添加创建者和创建日期。


说明:在设置模板时,注意 IDEA 的 @author 为${USER},而 eclipse 的@author 为${user},大小写有区别,而日期

的设置统一为 yyyy/MM/dd 的格式。


正例:

/**
*
* @author yangguanbao
* @date 2021/11/26
*
**/


4.【强制】方法内部单行注释,在被注释语句上方另起一行,使用 // 注释。方法内部多行注释使用 /* */

注释,注意与代码对齐。


5.【强制】所有的枚举类型字段必须要有注释,说明每个数据项的用途。


6.【推荐】与其用半吊子英文来注释,不如用中文注释说清楚。专有名词与关键字保持英文原文即可。


反例:“TCP 连接超时”解释成“传输控制协议连接超时”,理解反而费脑筋。


7.【推荐】代码修改的同时,注释也要进行相应的修改,尤其是参数、返回值、异常、核心逻辑等。


说明:代码与注释更新不同步,就像公路网与导航软件更新不同步一样,如果导航软件严重滞后,就失去了导航的意义。


8.【推荐】在类中删除未使用的任何字段和方法、内部类;在方法中删除未使用的参数声明与内部变量。


9.【参考】谨慎注释掉代码。在上方详细说明,而不是简单地注释掉。如果无用,则删除。


说明:代码被注释掉有两种可能性:1)后续会恢复此段代码逻辑。2)永久不用。前者如果没有备注信息,难以知晓注释动机。后者建议直接删掉即可,假如需要查阅历史代码,登录代码仓库即可。


10.【参考】对于注释的要求:第一、能够准确反映设计思想和代码逻辑;第二、能够描述业务含义,使别的程序员能够迅速了解到代码背后的信息。完全没有注释的大段代码对于阅读者形同天书,注释是给自己看的,即使隔很长时间,也能清晰理解当时的思路;注释也是给继任者看的,使其能够快速接替自己的工作。


11.【参考】好的命名、代码结构是自解释的,注释力求精简准确、表达到位。避免出现注释的另一个极端:过多过滥的注释,代码的逻辑一旦修改,修改注释又是相当大的负担。


反例:

// put elephant into fridge
put(elephant, fridge);


方法名 put,加上两个有意义的变量名称 elephant 和 fridge,已经说明了这是在干什么,语义清晰的代码不需要额外的注释。


12.【参考】特殊注释标记,请注明标记人与标记时间。注意及时处理这些标记,通过标记扫描,经常清理此类标记。线上故障有时候就是来源于这些标记处的代码。


1)待办事宜(TODO):(标记人,标记时间,[预计处理时间])表示需要实现,但目前还未实现的功能。这实际上是一个 Javadoc 的标签,目前的 Javadoc 还没有实现,但已经被广泛使用。只能应用于类,接口和方法(因为它是一个Javadoc 标签)。


2)错误,不能工作(FIXME):(标记人,标记时间,[预计处理时间])在注释中用 FIXME 标记某代码是错误的,而且不能工作,需要及时纠正的情况。

参考



  1. 2022 Java开发手册(黄山版).pdf


  1. 白话阿里巴巴Java开发手册(安全规约) - 李艳鹏 - 简书(https://www.jianshu.com/p/9528c4ea1504)


目录
相关文章
|
13天前
|
存储 缓存 监控
Java面试题:在Java中,对象何时可以被垃圾回收?编程中,如何更好地做好垃圾回收处理?
Java面试题:在Java中,对象何时可以被垃圾回收?编程中,如何更好地做好垃圾回收处理?
23 0
|
2天前
|
监控 Java
Java并发编程:深入理解线程池
在Java并发编程领域,线程池是提升应用性能和资源管理效率的关键工具。本文将深入探讨线程池的工作原理、核心参数配置以及使用场景,通过具体案例展示如何有效利用线程池优化多线程应用的性能。
|
10天前
|
安全 Java 开发者
Java并发编程中的线程安全性与性能优化
在Java编程中,处理并发问题是至关重要的。本文探讨了Java中线程安全性的概念及其在性能优化中的重要性。通过深入分析多线程环境下的共享资源访问问题,结合常见的并发控制手段和性能优化技巧,帮助开发者更好地理解和应对Java程序中的并发挑战。 【7月更文挑战第14天】
|
10天前
|
监控 Java API
Java并发编程之线程池深度解析
【7月更文挑战第14天】在Java并发编程领域,线程池是提升性能、管理资源的关键工具。本文将深入探讨线程池的核心概念、内部工作原理以及如何有效使用线程池来处理并发任务,旨在为读者提供一套完整的线程池使用和优化策略。
|
12天前
|
存储 安全 算法
深入理解Java并发编程:线程安全与性能优化
【5月更文挑战第72天】 在现代软件开发中,尤其是Java应用开发领域,并发编程是一个无法回避的重要话题。随着多核处理器的普及,合理利用并发机制对于提高软件性能、响应速度和资源利用率具有重要意义。本文旨在探讨Java并发编程的核心概念、线程安全的策略以及性能优化技巧,帮助开发者构建高效且可靠的并发应用。通过实例分析和理论阐述,我们将揭示在高并发环境下如何平衡线程安全与系统性能之间的关系,并提出一系列最佳实践方法。
|
2天前
|
存储 Java 调度
Java的并行编程有哪些优势
Java的并行编程有哪些优势
|
5天前
|
算法 安全 Java
Java并发编程的艺术与实践
【7月更文挑战第19天】在Java的世界中,并发编程是提升应用性能和响应能力的关键。本文将深入探讨如何利用Java的并发工具高效地构建多线程应用程序。我们将从基础的线程管理讲起,逐步过渡到高级的并发框架,如Executors和Futures,以及最新的CompletableFuture。同时,文章还会涵盖线程安全、锁机制、同步器等关键概念,确保读者能够在实战中避免常见的并发陷阱。
14 0
|
6天前
|
Java 开发者
Java并发编程之Executor框架详解
【7月更文挑战第18天】本文旨在深入探讨Java中的Executor框架,揭示其对并发编程的优化作用。通过解析Executor接口、ThreadPoolExecutor和ScheduledExecutorService等关键组件,文章展示了如何有效管理和控制线程资源。同时,结合实例分析,本文阐释了Executor框架在提高程序性能、简化代码结构方面的实际应用价值。旨在为Java开发者提供并发编程的高级工具,帮助他们构建更加高效、稳定的多线程应用。
|
10天前
|
Java 开发者
Java并发编程中的锁机制与性能优化
【7月更文挑战第14天】本文深入探讨了Java中锁的概念、种类及其在并发编程中的应用,并分析了不同锁类型对程序性能的影响。通过实例展示了如何合理选择和使用锁来提升应用的性能,同时指出了锁使用过程中可能遇到的问题和调优策略。旨在为Java开发者提供锁机制的深入理解和性能优化的实用建议。
15 0
|
13天前
|
Java 数据格式
Java面试题:简述Java Socket编程的基本流程,包括客户端和服务器的创建与通信。
Java面试题:简述Java Socket编程的基本流程,包括客户端和服务器的创建与通信。
16 0