优秀的java程序员怎么写注释的
前言
今天我们来说说如何编写Java注释。使用过Java的同学都非常熟悉,Java中有:
§单行注释// 这是单注释
§多行注释/*这是多行注释*/
§Javadoc注释/**这是javadoc注释*/
其实这里面还有很多细节呢,下面我们一一来揭晓
在这里相信有许多想要学习Java的同学,大家可以关注小编公众号卓越新腾。
哪些地方需要添加注释
首先,我们需要确定一下,添加注释的目的是什么?(手动思考10秒)。
我认为添加注释,是为了程序更容易理解与维护,特别是维护,更是对自己代码负责的一种体现。
那基于这样的目的,在日常开发中,我们需要在哪些地方添加注释呢?
§类,接口。
这一部分注释是必须的。在这里,我们需要使用javadoc注释,需要标明,创建者,创建时间,版本,以及该类的作用。如下所示:
package com.andyqian.utils;/*** @author: andy* @date: 18-01-05* @version: 1.0.0* @deion: 生成PDF 工具类*/public class PdfUtil {}
§方法
在方法中,我们需要对入参,出参,以及返回值,均要标明。如下所示:
/** * 生成pdf文件 * @param htmlContent 待生成pdf的 html内容 * @param file 生成pdf文件地址 * @see PdfUtils#getFontPath() * @return true 生成成功 false 生成失败 */ public static boolean generatePdf(String htmlContent,File file){ ... return result; }
§常量
对常量,我们需要使用多行注释,进行标明该常量的用途,如下所示:
/*** @author: andy* @date: 18-01-05* @version: 0.0.1* @deion:*/public class StatusConsts { /** * 博客地址 */ public static final String BLOG="www.andyqian.com";}
§关键算法上
在关键算法上,添加注释并且按照顺序依次标明,写明白该方法为什么这么做。如下所示:
/** * 应用场景: * 1.在windows下,使用Thread.currentThread()获取路径时,出现空对象,导致不能使用 * 2.在linux下,使用PdfUtils.class获取路径为null, * 获取字体路径 * @return 返回字体路径 */ private static String getFontPath(){ String path=""; // 1. ClassLoader classLoader= Thread.currentThread().getContextClassLoader(); URL url = (classLoader==null)?null:classLoader.getResource("/"); String threadCurrentPath = (url==null)?"":url.getPath(); // 2. 如果线程获取为null,则使用当前PdfUtils.class加载路径 if(threadCurrentPath==null||"".equals(threadCurrentPath)){ path = PdfUtils.class.getClass().getResource("/").getPath(); } // 3.拼接字体路径 StringBuffer stringBuffer = new StringBuffer(path); stringBuffer.append("/fonts/SIMKAI.TTF"); path = stringBuffer.toString(); return path; }
怎么添加注释?
1. IDEA 自动生成
对于类中的注释,我们可以通过IDEA自动生成。
如IDEA 可以通过:File->Settings->Editor->File and Code Templates->Includes->File Header来设置模板,这样新建文件时,IDEA会按照设置的模板,会自动生成一个注释,就不需要一个一个敲了。
其中标签有:
${USER} : 当前用户。
${DATE} : 当前日期。
${PACKAGE_NAME}:包名。
${TIME}: 当前时间。
${YEAR}: 当前年。
${MONTH}:当前月。
${DAY}: 当前日。
${HOURS}: 当前小时。
${MINUTE}: 当前分钟
1.注释引用
如果方法中引用了其他的方法,在注释中如何体现呢?细心的朋友,应该已经发现了,在上面的:
/** * 生成pdf文件 * @param htmlContent 待生成pdf的 html内容 * @param file 生成pdf文件地址 * @see PdfUtils#getFontPath() * @return true 生成成功 false 生成失败 */ public static boolean generatePdf(String htmlContent,File file){ ... return result; }
中的@see就有这个作用,其语法是:
@see package.class#method label@see #field@see #method(Type, Type,...)@see #method(Type argname, Type argname,...)@see #constructor(Type, Type,...)@see #constructor(Type argname, Type argname,...)
例如:
@see PdfUtils#getFontPath()
如果是同一个类中,package(包名全路径)可以省略。有相同功能的标签有:
{@linkpackage.class#metod}
/** * 生成pdf文件 * @return true 生成成功 false 生成失败 * @throws Exception * {@link PdfUtils#getFontPath()} */ public static boolean generatePdf(String htmlContent,File file){ .... }
其区别是:@see必须要在注释行首,{@link}可以在任意位置。
- 在IDEA中,我们可以选中方法通过快捷键Ctrl+D即可查看我们添加的注释,如下图所示:
1.如果需要引用外网的连接,我们可以通过HTML标签中的a标签来表示,如下所示:
@see <ahref="http://www.andyqian.com">博客地址</a>
以下为javadoc 需要熟知的注释标签:
@see 引用类/方法。
@author: 作者。
@date:日期。
@version: 版本号。
@throws:异常信息。
@param:参数
@return: 方法返回值。
@since: 开源项目常用此标签用于创建日期 。
{@value}: 会使用该值,常用于常量。
{@link} 引用类/方法。
{@linkplain} 与@link功能一致。
完整案例如下:
package com.andyqian.pdf.utils;import com.itextpdf.text.log.Logger;import com.itextpdf.text.log.LoggerFactory;import java.io.File;import java.net.URL;/*** @author: 鞠骞* @date: 18-01-05* @version: 1.0.0* @deion: 生成PDF 工具类*/public class PdfUtils { private static final Logger logger = LoggerFactory.getLogger(PdfUtils.class); /** * 生成pdf文件 * @param htmlContent 待生成pdf的 html内容 * @param file 生成pdf文件地址 * @see <a href="https://itextpdf.com/">https://itextpdf.com/</a> * @return true 生成成功 false 生成失败 */ public static boolean generatePdf(String htmlContent,File file)throws Exception{ ... return true; } /** * 应用场景: * 1.在windows下,使用Thread.currentThread()获取路径时,出现空对象,导致不能使用 * 2.在linux下,使用PdfUtils.class获取路径为null, * 获取字体路径 * @return 返回字体路径 */ private static String getFontPath(){ String path=""; // 1. ClassLoader classLoader= Thread.currentThread().getContextClassLoader(); URL url = (classLoader==null)?null:classLoader.getResource("/"); String threadCurrentPath = (url==null)?"":url.getPath(); // 2. 如果线程获取为null,则使用当前PdfUtils.class加载路径 if(threadCurrentPath==null||"".equals(threadCurrentPath)){ path = PdfUtils.class.getClass().getResource("/").getPath(); } // 3.拼接字体路径 StringBuffer stringBuffer = new StringBuffer(path); stringBuffer.append("/fonts/SIMKAI.TTF"); path = stringBuffer.toString(); return path; }}
添加注释时的一点建议
1.类中,接口等必须有创建时间,创建人,版本号,描述等注释。
2.注释不是越多越好,比如:get/set方法就不需要写注释。更不需要每一行都写注释。
3.注释需要写的简明易懂。特别是方法的参数,以及返回值。
4.每一次修改时,相应的注释也应进行同步更新。
5.在类,接口,方法中,应该都使用/** */javadoc注释。因为这样调用者就不需要进入方法内部才知道方法的用处。提高编码效率。
6.方法代码中如果有顺序之分,最好将代码也加上序号,如1,2,3等。
7.枚举中的每一个值都需要添加注释。
小结
写注释是一个好习惯,能让自己和团队都受益,如果你接手一个一丁点注释都没有的项目,那么上一个程序员就倒霉了(此处省略N个字),不知你们有没有看过开源项目的源码,那注释写的相当详细,大家可以多多参考,争取别做一个”倒霉”的程序员。
优秀的java程序员怎么写注释的相关推荐
- 如何写一份优秀的Java程序员简历?
hello,大家好! 之前给小伙伴们分享过大厂的面经汇总, 面试题刷的怎么样了? 简历准备好了吗? 今天来讨论一下 如何写一份优秀的Java程序员简历 也会分享几份优秀的大厂简历模板, 下方公众号回复 ...
- 优秀的Java程序员应具备哪些编程技术?
想要成为一名合格的java程序猿,需要学习的知识是有很多的,但是基础知识一定要非常牢固,基础不牢固的程序员,随时都会被新的知识和技术所淘汰,下盘不稳风一吹就倒,那么具体作为一个优秀的Java程序员应具 ...
- 成为优秀的Java程序员要具备哪些技能?
Java是热门的编程语言,热衷技术,掌握一门语言,我们最重要的是知识的积累和运用,那我们需要掌握哪些技能才能成为优秀的Java程序员呢?小编来为大家解答一波. 1.拥有扎实的基础和深刻理解能力 Jav ...
- 没有学历文凭,如何成为一名优秀的 Java 程序员?
作为编程语言界的常青藤 Java,无论是在企业级应用,还是后端开发中,均有着无可替代的地位.而对于 Java 的入门,很多新手们不可避免的会走一些弯道.那么,如何才能有效地避开这些误区?又该如何快速实 ...
- 没有学历文凭,如何成为一名优秀的 Java 程序员
"如何成为一名优秀的Java程序员"不是只字片语就能回答清楚的.没有相关的学位证书,你也可以被称为一名优秀的Java程序员. 你只需集中精力,主动利用网上丰富的资源,投入足够的时间 ...
- 为何优秀的Java程序员如此吃香?
最近一个月,我们从客户经理那里听到不少关于「Java程序员供不应求」的消息.今年6月,在北京已签约的103家企业中,对Java程序员的需求总量就高达334名,平均每家企业至少需要3名以上Java程序员 ...
- 优秀的Java程序员必须了解GC的工作原理
一个优秀的Java程序员必须了解GC的工作原理.如何优化GC的性能.如何与GC进行有限的交互,因为有一些应用程序对性能要求较高,例如嵌入式系统.实时系统等,只有全面提升内存的管理效率 ,才能提高整个应 ...
- 程序员用学位证吗_没有学位如何成为一名优秀的Java程序员
程序员用学位证吗 掌握Java的道路是漫长而棘手的. 但是,在我从事编码工作的那几年中,我获得了一两个提示. 但是,如何成为一名优秀的Java程序员不是一个简单的问题? 您不需要任何正式培训. 您无需 ...
- 一个优秀的Java程序员必须了解的GC机制
一个优秀的Java程序员必须了解GC的工作原理.如何优化GC的性能.如何与GC进行有限的交互,有一些应用程序对性能要求较高,例如嵌入式系统.实时系统等,只有全面提升内存的管理效率,才能提高整个应用程序 ...
- java 哪一个gc好_优秀的Java程序员必须了解的GC哪些
作者丨灵犀一脚C http://www.cnblogs.com/ckwblogs/p/5975921.html 一个优秀的Java程序员必须了解GC的工作原理.如何优化GC的性能.如何与GC进行有限的 ...
最新文章
- R语言字符串处理函数
- URL加随机数的作用
- Windows的Java_HOME环境变更配置
- laravel定时任务
- GridView RowCommand 获取列值
- python读取word文件并替换部分文字_python实现替换word中的关键文字(使用通配符)...
- 雨滴桌面rainmeter素材_win10 桌面如何做到清爽好看?这篇教程给你答案
- 一文详解计算机视觉五大技术:图像分类、对象检测、目标跟踪、语义分割和实例分割
- python中字典按键或键值排序_[宜配屋]听图阁
- Pandas index详解
- Office Word2019您正试图运行的函数包含有宏或需要宏语言
- Matlab二维图导入ansys,(原创教程)利用Matlab对ANSYS数据进行后处理.pdf
- 初探socket 报式
- 微信小程序绑定手机号登录流程
- easyui实例案例介绍
- Linux计算节点怎么关闭,OpenStack 删除无用的计算结点
- SSH远程访问开发板
- Jenkins部署maven项目找不到jar包解决
- 揭秘淘宝买衣服潜规则,你们吃亏吃大了!
- 2022年上海医院三基考试仿真试题(含答案)