简单的 Getter/Setter 注释 [英] Simple Getter/Setter comments

问题描述

您使用什么约定来评论 getter 和 setter?这是我想了很长时间的事情，例如:

What convention do you use to comment getters and setters? This is something I've wondered for quite some time, for instance:

/**
 * (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 来说，措辞几乎完全相同.

I always find I'm pretty much writing the exact same thing for 1a/b and 2a/b, something like 1a) Sets the salary of the employee, 1b) the salary of the employee. It just seems so redundant. Now I could see for something more complex you might write more in the (a) parts, to give context, but for a majority of the getters/setters out there the wording is almost exactly the same.

我只是好奇，对于简单的 getter/setter，是否可以只填写 (a) 部分或 (b) 部分.

I'm just curious if, for the simple getters/setters its ok to only fill in either the (a) part OR the (b) part.

你怎么看?

推荐答案

我通常只为 setter 填写 param 部分，为 getter 填写 @return 部分:

I usually just fill the param part for setters, and the @return part for getters:

/**
 * 
 * @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 的警告)就会干净利落，并且没有重复.

That way javadoc checking tools (such as Eclipse's warnings) will come out clean, and there's no duplication.

这篇关于简单的 Getter/Setter 注释的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！