简单的Getter / Setter注释

你用什么约定来评论吸气剂和吸附剂? 这是我想了很长一段时间,例如:

/** * (1a) what do you put here? * @param salary (1b) what do you put here? */ public void setSalary(float salary); /* * (2a) what do you put here? * @return (2b) */ public float getSalary(); 

我总是发现我写了1a / b和2a / b完全相同的东西,例如1a)设置员工的工资,1b)员工的工资。 这似乎是多余的。 现在我可以看到更复杂的东西,你可以在(a)部分写更多的东西来给出上下文,但是对于大部分的获取者/引导者来说,这些措辞几乎是完全相同的。

我只是好奇,对于简单的getter / setters来说,它只能填写(a)部分或(b)部分。

你怎么看?

我通常只填写setter的param部分,getter的@return部分:

 /** * * @param salary salary to set (in cents) */ public void setSalary(float salary); /** * @return current salary (in cents, may be imaginary for weird employees) */ public float getSalary(); 

这样javadoc检查工具(比如Eclipse的警告)就会变得干净,没有重复。

绝对没有意义 – 你最好没有这种垃圾混乱你的代码:

 /** * Sets the foo. * * @param foo the foo to set */ public void setFoo(float foo); 

非常有用,如果保证:

 /** * Foo is the adjustment factor used in the Bar-calculation. It has a default * value depending on the Baz type, but can be adjusted on a per-case base. * * @param foo must be greater than 0 and not greater than MAX_FOO. */ public void setFoo(float foo); 

特别是在领域模型中,对财产实际上意味着什么的解释是至关重要的。 每当我看到一个充满了只有投资银行家,生物化学家或者量子物理学家才能理解的名字晦涩的属性的豆子,并且这些评论解释说setGobbledygook()方法“设定了这个大餐”,我想扼杀一个人。

一般没有什么,如果我可以帮助它。 吸气和安装人员应该是不言自明的。

我知道这听起来像是一个没有答案的东西,但我试图用我的时间来评论需要解释的事情。

如果他们有某种副作用,或者在初始化之外需要某种先决条件(即:从数据结构中删除项目,或者为了设置您需要的东西),我只会担心评论getter和setter首先要有x和y)。 否则这里的评论是相当多余的。

编辑:另外,如果你发现在你的getter / setter中涉及到很多副作用,你可能需要改变getter / setter来使用不同的方法名(例如:push和pop来堆栈)[感谢下面的评论]

问问你自己,什么时候让人们看到JavaDocs(从浏览器)的评论。 很多人都说文档不是必须的,因为它很明显。 如果该字段是私有的(除非你明确地打开专用字段的JavaDocs),这将不成立。

在你的情况下:

 public void setSalary(float s) public float getSalary() 

目前尚不清楚工资是以什么forms表示的,分美元,英镑,人民币?

当loggingsetter / getters,我喜欢分开什么编码。 例:

 /** * Returns the height. * @return height in meters */ public double getHeight() 

第一行说它返回高度。 返回参数文件的高度是米。

为什么他们不包括一个引用标签来让你评论字段值和来自getter和setter的引用。

 /** * The adjustment factor for the bar calculation. * @HasGetter * @HasSetter */ private String foo; public String getFoo() { return foo; } public void setFoo() { this foo = foo; } 

这样的文档适用于getter和setter以及字段(如果私人javadocs被打开的话)。

这种样板可以通过使用Project Lombok来避免。 只要logging字段variables,即使它是private ,并让Lombok注释生成适当的logging的getter和setter。

对我而言,单单这个好处是值得的。

我真的很失望的答案基本上说综合文件是浪费时间。 你的API的客户端应该怎么知道一个名为setX的方法是一个标准的JavaBean属性设置器,除非你在文档中说得这么清楚

如果没有文件,呼叫者不知道该方法是否有任何副作用,除了通过交叉手指来遵循明显的惯例。

我确信我不是唯一一个在这里遇到困难的人,那就是一个名为setX的方法不仅仅是设置一个属性。

如果在getter / setter中没有特殊的操作,我通常会写:

随着Javadoc(与私人选项):

 /** Set {@see #salary}. @param {@link #salary}. */ public void setSalary(float salary); 

和/或

 /** * Get {@see #salary}. * @return {@link #salary}. */ public float salary(); 

与Doxygen(与私有萃取物select):

 /** @param[in] #salary. */ public void setSalary(float salary); /** @return #salary. */ public float salary(); 

评论访问者,特别是如果他们不在任何地方做任何操作,是不必要的,浪费指尖。

如果有人读你的代码不能理解person.getFirstName()返回一个人的名字,你应该尝试一切权力让他被解雇。 如果它做了一些数据库的魔法,会抛出一些骰子,叫名字秘书得到名字,可以认为这是一个不平凡的操作,并logging下来。

另一方面,如果你的person.getFirstName()没有返回一个人的名字,那么我们不要去那里,对吗?

可以填写(b)部分,特别是如果你在字段声明中注明了什么是字段的话。

如果javadoc不添加任何东西,我删除javadoc并使用自动生成的注释。

我总是填写这两个。 打字所花费的时间可以忽略不计,一般而言,更多的信息总是比较less。

如果它是一个getter / setter,它应该被logging。

我在这里离题,但如果它可以成为一个属性,也许这对于类的用户更简单的编码更好。 我进一步离题,但至于所有的“Java”在他们的任何地方的评论,谁说这是Java? (标签,但问题可以应用在任何地方)

如果字段名称足够描述内容,则不要放置任何东西。

一般来说,让代码自立,尽可能避免评论。 这可能需要重构。

编辑:上面指的只是获得者和制定者。 我相信任何非微不足道的事情都应该正确对待。