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

javadoc 开源项目

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

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

javadoc 开源项目

javadoc 开源项目_在下一个项目中不使用JavaDoc的5大原因相关推荐

python 创意项目_选择创意项目您需要知道的7个步骤
python 创意项目 There are obvious surface-level positives and negatives to most projects. If you look be ...
android studio引入lib,Android studio项目引入另外一个项目做为Lib
Android studio项目引入另外一个项目做为Libary 方法一:使用Android studio 导入lib项目: 注意: lib项目更改处:html 在build.gradle 文件下将 ...
C#中同一解决方案下，一个项目调用另一个项目中的窗体
在实际应用中,一个程序大多是多人共同完成,如果最初对窗体命名时没沟通好出现重名,这样直接在项目中导入窗体(添加现有项)容易造成调用混乱.而且大多时候各自开发的是独立模块,单纯导入窗体而不导入相应的输入 ...
eclipse中一个项目引用另一个项目的方法
我们在开发的时候,有时候需要把一个大的项目打散,尤其是现在微服务的架构很流行,一个大的项目往往被拆成很多小的项目,而有的项目作为公共工程被独立出来,比如有个工程专门提供各种Util工具类,有的工程专门 ...
it项目经理带一个项目的完整_如何控制IT项目需求范围？千万别让用户把你带沟里……...
IT项目管理之需求范围控制篇作为一名项目经理,如果您遇到这种情况该怎么办?客户仅仅付给了你一块蛋糕的钱,但他却想拥有一顿非常丰盛的晚餐.如果有一位项目经理能够让客户非常满意的只带着一块蛋糕离开,那么 ...
安卓期末作品小项目_每日一个财务小知识——洞悉洞晰财务报告第一季
财务报告洞悉洞晰财务报告目录 01/账务报告概述 02/资产负债表 03/利润表 04/现金流量表 05/所有者权益变动表 06/附注一.财务报告概述 (一)财务报告及其目标财务报告是指企业对 ...
netbeans java项目_如何在NetBeans中组合两个Java项目
我使用NetBeans为我的Java类创建了两个独立的项目 . 最终,我想把两者结合起来 . 我希望他们俩都在同一个输出窗口上播放 . 一个项目是使用JavaFX创建的,一个是Java应用程序 . J ...
我的项目_唐诗可视化项目
目录一.项目:唐诗可视化二.技术选型三.数据库表的设计四.选型技术的简单使用Demo(预研阶段) 五.实现思路六.唐诗爬取模块实现单线程版本: 多线程版本: 线程池: 改进线程池的版本: ...
数仓建模项目_音乐数据项目火力全开，技能双倍提升！
↑ 点击上方"尚学堂"关注我们音乐数据中心数仓综合项目 1项目介绍音乐数据中心项目是大型企业级综合数仓项目,此项目针对音乐数据进行分析,构建数据仓库,建立用户.机器.内容等主题 ...

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

javadoc 开源项目_在下一个项目中不使用JavaDoc的5大原因相关推荐

最新文章

热门文章