简单的Getter / Setter评论

时间:2009-06-22 19:26:53

标签: java comments javadoc setter getter

您使用什么约定来评论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 / setter来说,措辞几乎完全相同。

我只是好奇,如果对于简单的getter / setter来说,只需填写(a)部分或(b)部分即可。

您怎么看?

15 个答案:

答案 0 :(得分:165)

绝对毫无意义 - 如果没有这种垃圾使你的代码混乱,你会更好:

/**
 * 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()方法“设置了gobbledygook。”,我想扼杀某人。

答案 1 :(得分:78)

我通常只为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的警告)就会变得干净,并且没有重复。

答案 2 :(得分:35)

一般来说,没有,如果我可以帮助它。吸气剂和二传手应该是不言自明的。

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

答案 3 :(得分:33)

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

编辑:此外,如果您确实发现getter / setter中涉及很多副作用,您可能希望将getter / setter更改为具有不同的方法名称(即:push和pop for a stack) [感谢下面的评论]

答案 4 :(得分:12)

问问自己,当评论被视为JavaDocs(来自浏览器)时,您希望人们看到什么。许多人说文档没有必要,因为它很明显。如果字段是私有的,则不会成立(除非您明确为私有字段启用JavaDocs)。

在你的情况下:

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

目前尚不清楚薪水表示的是什么。它是美分,美元,英镑,人民币?

在记录setter / getters时,我喜欢将其与编码分开。例如:

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

第一行表示它返回高度。返回参数记录了高度以米为单位。

答案 5 :(得分:9)

为什么他们不只是包含一个引用标记,以便您对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)。

答案 6 :(得分:6)

使用Project Lombok可以避免使用这种样板文件。只记录字段变量,即使它是private,并让Lombok注释生成正确记录的getter和setter。

对我来说,这个好处值得costs

答案 7 :(得分:4)

我对答案感到非常失望,基本上说综合记录是浪费时间。您的API的客户端应该如何知道名为setX的方法是标准JavaBean属性setter ,除非您在文档中明确说明

如果没有文档,如果方法有任何副作用,调用者就不会知道任何副作用,除非他们指责所遵循的明显惯例。

我确信我不是唯一一个不幸发现一个名为setX的方法比设置属性更多的方法。

答案 8 :(得分:4)

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

使用Javadoc(带私有选项):

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

和/或

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

使用Doxygen(带私有提取选项):

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

/** @return #salary. */
public float salary();

答案 9 :(得分:1)

如果字段名称足以描述内容,请不要放置任何内容。

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

编辑:以上仅指吸气剂和制定者。我相信任何不平凡的事都应该适当地进行javadoc。

答案 10 :(得分:1)

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

如果有人在阅读你的代码时无法理解person.getFirstName()会返回一个人的名字,那么你应该尝试一切能力让他被解雇。如果它做了一些数据库魔法,抛出一些骰子,调用名字秘书获得第一个名字,可以安全地假设它是一个非常重要的操作,并且记录得很好。

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

答案 11 :(得分:0)

可以填写(b)部分,特别是如果你在字段声明上发表评论,指出字段的全部内容。

答案 12 :(得分:0)

如果javadoc没有添加任何内容,我会删除javadoc并使用自动生成的注释。

答案 13 :(得分:0)

我总是填写两个。打字所花费的额外时间可以忽略不计,一般而言,更多信息优于更少。

答案 14 :(得分:0)

如果是getter / setter,则应记录下来。

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