在下一个项目中不使用JavaDoc的5大原因

JavaDoc对于框架和库的开发是绝对必要的,这些框架和库为其他框架(例如Spring Framework,JDK)提供了公共接口。 对于内部企业软件和/或产品开发,我有以下原因会在将来忽略“ 100%JavaDoc策略”。

1)大约95%的评论没有附加值的观察

如果您有一个JavaDoc在项目中是强制性的规则,则大多数开发人员将使用JavaDoc生成向导(例如http://jautodoc.sourceforge.net/ )。 这些生成的评论很快,并且创建了几乎一文不值的内容。 但是对于像PMD这样的静态代码分析工具,一切看起来都不错。

现有的大多数JavaDoc描述都解释了WHAT,而不是WHY。 每个开发人员都应该能够阅读源代码,而事实就是代码。 通常,仅需要注释即可了解开发人员为何决定使用当前解决方案。 在某些情况下,对引用的基本概念的提示可能会有所帮助,例如设计模式,教科书章节,标准算法。

2)使用断言来检查有效参数比纯文本描述更有效

即使使用100%JavaDoc和高质量的描述,只要没有明显的问题出现,许多开发人员就不会阅读注释。 对于这些情况,对具有断言和/或验证功能的方法的有效输入进行自动检查会有所帮助。 Spring框架是使用Asserts的一个很好的例子。 在开发或测试期间的异常比不读注释有更多帮助。

3)源代码的可读性越来越差

广泛的JavaDoc可能不是最关键的缺点是可读性差。 屏幕空间有限。 这也可能是错误的根源,因为我们是人类,屏幕上显示的更多代码意味着更好的概览。

4)随着时间的流逝,很多评论都错了

假设您有完善的JavaDoc注释,并且有一些增强请求,缺陷或重构。 许多评论将是不正确的,因为没有人花时间来更新它们。 这是一个非常糟糕的情况。 开发人员应该在评论或新实现中相信测试吗? 没有文件比不一致或过时的文件更好。

5)重构将更慢

在大多数情况下,借助现代开发工具支持,重构是一项快速而轻松的工作。 更新JavaDoc仍然是一个手动过程,需要很多时间。 这导致由于JavaDoc导致不需要重构的情况。
建议不只是背面和白色。 在某些情况下,JavaDoc非常有意义,并为维护团队创造了价值。 在团队中讨论何时使用JavaDoc。 我保证将来会这样做。

参考:来自JCG合作伙伴 Markus Sprunck的Software Engineering Candies博客上的下一个项目中未使用JavaDoc的5大理由 。


翻译自: https://www.javacodegeeks.com/2012/06/top-5-reasons-for-not-using-javadoc-in.html

本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如若转载,请注明出处:http://www.mzph.cn/news/372616.shtml

如若内容造成侵权/违法违规/事实不符,请联系多彩编程网进行投诉反馈email:809451989@qq.com,一经查实,立即删除!

相关文章

NPOI操作Excel辅助类

/// <summary> /// NPOI操作excel辅助类 /// </summary> public static class NPOIHelper {#region 定义与初始化public static HSSFWorkbook workbook;[Flags]public enum LinkType{网址,档案,邮件,内容};private static void InitializeWorkbook(){if (workbook …

JSP九大内置对象,七大动作,三大指令

JSP之九大内置对象 隐藏对象入门探索 Servlet 和JSP中输出数据都需要使用out对象。Servlet 中的out对象是通过getWriter()方法获取的。而JSP中没有定义out对象却可以直接使用。这是因为out是JSO的内置隐藏对象。JSP中的常见的9个内置隐藏对象如下 out输出流对象 隐藏对象out是…

matlab变步长的梯形公式,用变步长梯形法计算积分∫sinx/x*x的近似值(二分二次即可)...

共回答了20个问题采纳率&#xff1a;90%题目没写全吧?现假定积分区间为[0,1],教材《数值分析》(华中科技大学出版)第87页,例题4.2就有详细的解答.貌似题目也有错?确定分母是【x^2】?现在附上该例题(分母是x)的全部解答过程&#xff1a;先对整个区间[0,1]使用梯形公式.对于函…

使用Cloud SQL的Google App Engine全文搜索

许多Google AppEngine开发人员一直在等待全文搜索功能&#xff0c;特别是来自网络上最大的搜索引擎Google。 很高兴看到Google团队正在努力&#xff0c;您可以在Google I / O 2011大会上签到&#xff1a; Bo Majewski和Ged Ellis进行的全文本搜索 。 据我所知&#xff0c;非常有…

php 数组值sum,php sum数组值(如果特定列的值重复)

我有一个阵列。我要检查是否有重复的费用,如果有,我要用相同的费用列汇总所有值。[12] > Array([type] > Other Miscellaneous Fees[fee] > 158[amount] > -22.56[code] > COL_AUDIO[feedesc] > COLLEGE AUDIO VISUAL FEE)[13] > Array([type] > Other…

hdu-5734 Acperience(数学)

题目链接&#xff1a; Acperience Time Limit: 4000/2000 MS (Java/Others) Memory Limit: 65536/65536 K (Java/Others) Problem DescriptionDeep neural networks (DNN) have shown significant improvements in several application domains including computer vision and…

Ninject依赖注入(一)

Ninject学习笔记&#xff08;一&#xff09; Ninject学习笔记&#xff08;一&#xff09;理解依赖注入DI概念什么是DI&#xff1f;DI是如何工作的&#xff1f;什么是DI容器使用Ninject如何使用NinjectNinject对象生命周期暂时范围单例范围线程范围请求范围自定义范围Ninject模块…

我如何向团队解释依赖注入

最近&#xff0c;我们公司开始开发基于Java的新Web应用程序&#xff0c;经过一些评估过程&#xff0c;我们决定使用Spring。 但是许多团队成员并不了解Spring和Dependency Injection的原理。 因此&#xff0c;我被要求给出一个速成班&#xff0c;介绍什么是Spring上的依赖注入和…

可以添加自定义的Select控件

1.控件dom <select name"WebSiteTarget" id"WebSiteTarget" class"w1" onchange"editable2(this);"><option value"-1">请选择城市</option><option>福州</option><option>厦门</op…

innodb_io_capacity =innodb_lru_scan_depth*inoodb_buffer_pool_instances。与 checkpoint

innodb_lru_scan_depth:每个缓冲池刷脏页的能力 innodb_io_capacity: iops inoodb_buffer_pool_instances8 :缓冲池的个数 .关系&#xff1a; innodb_io_capacity > innodb_lru_scan_depth * inoodb_buffer_pool_instances 转载于:https://www.cnblogs.com/zengkefu/…

Java中的责任链模式

当应有几个处理器来执行某项操作并为这些处理器定义特定顺序时&#xff0c;就需要采用责任链设计模式。 在运行时处理器顺序的可变性也很重要。模式的UML表示如下&#xff1a; 处理程序定义处理器对象的一般结构。 这里的“ HandleRequest”是抽象处理器方法。 处理程序还具有自…

php的excel源码下载,PHPExcel-5 - 源码下载|Windows编程|其他小程序|源代码 - 源码中国...

文件名大小更新时间PHPExcel02019-05-11PHPExcel\.gitattributes702019-01-02PHPExcel\.gitignore1082019-01-02PHPExcel\.travis.yml5122019-01-02PHPExcel\16329.xlsx510662019-05-11PHPExcel\19093.xlsx511932019-05-11PHPExcel\43877.xlsx530952019-05-11PHPExcel\62045.xl…

使用Visual Studio Code开发Asp.Net Core WebApi学习笔记(六)-- 依赖注入

本篇将介绍Asp.Net Core中一个非常重要的特性&#xff1a;依赖注入&#xff0c;并展示其简单用法。 第一部分、概念介绍 Dependency Injection&#xff1a;又称依赖注入&#xff0c;简称DI。在以前的开发方式中&#xff0c;层与层之间、类与类之间都是通过new一个对方的实例进行…

基于JAX-WS的webService开发实例

最近因为工作原因接触到webService&#xff0c;所以记录下开发中碰到的问题&#xff0c;方便自己以后复习&#xff0c;顺便发扬一下开源精神。刚刚接触webServie如果有什么错误欢迎大家指正。 本地环境&#xff1a;myEclipse10.6 tomcat7 JDK7 jaxws-ri-2.2.10 第一步&#xff…

完整的WebApplication JSF EJB JPA JAAS –第2部分

视图–创建和JSF设置 本教程是第1部分的继续。 让我们创建一个新的Dynamic Web Project 。 如下图所示创建它&#xff1a; 注意&#xff1a;在某些时候&#xff0c;Eclipse会询问您是否要添加JSF功能&#xff08;自动完成&#xff09;&#xff0c;然后启用它。 就像下面的屏幕…

lempel ziv matlab,基于Python的LempelZiv算法的熵估计

此函数允许估计时间序列的熵。它基于Lempel-Ziv压缩算法。对于长度为n的时间序列&#xff0c;熵估计为&#xff1a;E(1/n和L_i)^-1 ln(n)式中&#xff0c;L逯i是从位置i开始的最短子串的长度&#xff0c;该子串之前没有从位置1出现到i-1。当n接近无穷大时&#xff0c;估计的熵收…

Android使用绘图Path总结

Path作为Android中一种相对复杂的绘图方式&#xff0c;官方文档中的有些解释并不是很好理解&#xff0c;这里作一个相对全面一些的总结&#xff0c;供日后查看&#xff0c;也分享给大家&#xff0c;共同进步。 1.基本绘图方法 addArc(RectF oval, float startAngle, float swee…

2017.3.23下午

下午通过对OSPF基本原理进一步的学习&#xff0c;对上午学习的内容进行了复习。 转载于:https://www.cnblogs.com/bgd140206206/p/6606192.html

编写Eclipse插件教程–第1部分

Eclipse是三个最受欢迎的Java开发IDE之一。 其成功的原因之一是其可扩展性。 对于任何知道该怎么做并且已经做到的人来说&#xff0c;编写eclipse插件都可以非常轻松快捷。 不幸的是&#xff0c;第一次在Eclipse中进行操作可能会非常耗时且令人沮丧。 Eclipse框架非常庞大&…

简单Window下 Android Studio的安装

&#xff08;1&#xff09;首先安装JDK 下载JDK 本人觉得官方网站下JDK比较慢&#xff0c;可以直接百度JDK&#xff0c;&#xff08;如果是64位 百度搜索记得64位&#xff09; 类似于这样的下载 安装可以看下教程&#xff0c;包括环境变量的配置 如何安装JDK &#xff08;2&…