简单的 Getter/Setter 注释

您使用什么约定来注释 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)部分是否没有问题。

你觉得怎么样？

82151 次浏览
小开

可以填写(b)部分，特别是如果您在字段声明中放置一个注释，指示该字段的内容。

小开

一般来说没什么，如果我能帮上忙的话。读取器和设置器应该是不言而喻的。

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

小开

如果 javadoc 没有添加任何东西，我就删除 javadoc 并使用自动生成的注释。

小开

如果字段名充分描述了内容，则不要放置任何内容。

一般来说，让代码独立存在，尽可能避免注释。这可能需要重构。

编辑: 上面只提到了 getter 和 setter。我相信任何重要的东西都应该被正确的 javadoc。

小开
最佳答案

我通常只填充 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 的警告)就可以很干净，而且不会有重复。

小开

如果 getter 和 setter 有某种副作用，或者需要初始化之外的某种先决条件(比如: get 将从数据结构中删除一个条目，或者为了设置某些东西，你需要先设置 x 和 y) ，那么我只担心注释 getter 和 setter。否则这里的注释就是多余的。

编辑: 另外，如果你发现你的 getter/setter 有很多副作用，你可能需要改变 getter/setter 的方法名(例如: push and pop for a stack)[感谢下面的评论]

小开

注释访问器，特别是如果它们不在任何地方执行任何操作，是不必要的，而且是浪费指尖。

如果有人读你的代码不能理解 person.getFirstName()返回一个人的名字，你应该尽你所能让他被解雇。如果它做了一些数据库魔术，掷几个骰子，调用部长的名字得到第一个名字，这是安全的假设，这是一个非平凡的操作，并记录它很好。

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

小开

我总是两个都填。一般来说，额外的输入时间可以忽略不计，信息越多越好。

小开

我真的很失望的答案基本上说，全面的文档是浪费时间。你的 API 的客户端如何知道一个称为 setX的方法是 标准 JavaBean 属性设置程序，除非是 你在文件里说得很清楚？

如果没有文档，调用者根本不知道该方法是否有任何副作用，除非他们对遵循的明显约定交叉手指。

我肯定不是这里唯一一个不幸发现称为 setX的方法不仅仅是设置一个属性，而且还有很多其他功能的人。

小开

问问自己，当评论被视为 JavaDocs (从浏览器)时，你想让人们看到什么。许多人说，文档是不必要的，因为它是显而易见的。如果该字段是私有字段(除非您显式地为私有字段打开 JavaDocs) ，则这种情况不会持续下去。

就你而言:

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

不清楚工资是用什么表示的，是美分、美元、英镑还是人民币？

在记录 setter/getter 时，我喜欢将 what 从编码中分离出来。例如:

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

第一行表示返回高度，返回参数表示高度以米为单位。

小开

完全没有意义——没有这些乱七八糟的东西，你会过得更好:

/**
* 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 ()方法“设置了这些晦涩难懂的名字。”，我想勒死一个人。

小开

为什么它们不包含一个 reference 标记，让您可以注释字段值以及来自 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)。

小开

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

使用 Javadoc (带有私有选项) :

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

及/或

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

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

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


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

使用 龙目岛计划可以避免这种类型的样板。只要记录 field 变量，即使它是 private，并让龙目岛注释生成正确记录的 getter 和 setter。

对我来说，这个好处本身就值得 成本。


提交答案