如何创建一个强制我编写javadoc注释的git钩子?

时间:2017-02-02 18:25:15

标签: java git documentation javadoc githooks

有没有办法让我以某种方式解析我的java代码文件并查找java doc注释?我想确保我已经为类和类的每个方法(或者其他所有方法)编写了javadoc。这可能吗?

1 个答案:

答案 0 :(得分:2)

严重的不回答:执行此操作。随后会有明确的解释;但我的所有投入都源于对这些主题的大量经验。

重点是:迟早(更快!)你会遇到你真的想要改变git的情况。知道你需要javadoc来实现这一点,你将开始放下虚拟内容,例如:

/** just to make the commit hook happy; @TODO: replace with real content */

我向你保证:迟早你会发现你的代码库里有很多这样的@TODOS烂了好几天,几周,几个月。因为最终,向支付薪水的客户提供新功能比修复你在某处获得的15个@TODO更重要。我说15了吗?啊,那是上周。现在我们有25 ...(LeBlanc's law 以后等于永远不会开始!保证)

换句话说:如果你希望在所有地方都拥有javadoc,但你的纪律不够好" 今天在没有这种强制执行的情况下实现这一目标;那将导致低质量的javadoc。

除此之外:专注于"清洁代码"我认为今天几年的做法:单独使用javadoc是答案。虽然我在一家大型企业工作,团队遍布全球。

恰恰相反。当人们接受培训以编写“可读”字样时。代码,他们实际上并不需要任何(或只是微小的)javadoc来实现这一目标。因为那时他们的设计和命名技巧处于一个水平,代码变得易于阅读而没有太多的javadoc。

如果人们没有接受过关于这项技能的训练,他们往往会创造无用的javadoc。我无法告诉你我多久会告诉别人禁用那个在生成新类时创建绝对无用的@author标记的eclipse模板。并猜测:仍然有无数次出现的eclipse生成的javadocs ......在生成之后,任何开发人员都从未触及。

长话短说:创建有用的 javadoc需要很多纪律和技巧。如果你已经缺乏纪律,那么执行一些"一些javadoc必须在那里"规则将提高代码质量!

最后:我并不是说一个人不应该完全看待这些事情。但我宁愿建议

  1. 定义如何编写javadoc的通用指南;什么信息是强制性的;什么样的元素需要javadoc
  2. 基于此,找到自动检查
  3. 的方法
  4. 然后在常规基础上收集此类信息(例如在夜间构建期间)并密切关注此类统计数据