简单的 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屋!