Java comment for getter and setter method
My question is, should I comment on the following:
/**
* Getter for {@link #auto_key}
* @return {@link #auto_key}
*/
public String getAuto_key() {
return auto_key;
}
/**
* Setter for {@link #auto_key}
* @param auto_key the {@link #auto_key} to set
*/
public void setAuto_key(String auto_key) {
this.auto_key = auto_key;
}
Basically, I want to ask, using {@link} in the comment for the getter and setter method is correct? or should I use a normal comment without using {@link}? and this way is java standard or not?
source to share
-
I would suggest creating a self-contained documentation for your set / get methods while still using
{@link}
, i.e. for both. That way, when the field is available, people can still get to their documentation. If it becomes private afterwards due to refactoring, you won't end up with a bunch of incomplete Javadocs that need to be changed as well. -
While the documentation for setter / getter methods might seem like bloated code, I would still suggest creating one for several reasons:
-
It gives you a standard location to mention important information, such as setter arguments that shouldn't be,
null
or getters that are highly inefficient in a particular interface implementation. -
It does not assume that the reader automatically knows what the backing field is doing. Sure,
setLength()
can be descriptive enough in some contexts, but what exactly does it dosetLimit()
? -
It does not imply that there is a backing field or that get / set methods are only executed in a particular implementation. Unfortunately, when refactoring is limited to compatibility issues, various artifacts are left behind. For example.
setLimit()
can delegatesetSizeLimit()
, which should be noted. -
Removes any ambiguity. What you consider common sense may not be straightforward for all people. Without documentation, any assumptions will be made which may or may not be true. For example, in a list implementation,
setLength(0)
also sets all contained references tonull
or not? -
Most importantly, it allows the Javadoc policy to be reduced to a simple "document everywhere". On the other hand, a policy with various exceptions will inevitably lead to weakness and code that will ultimately go undocumented.
-
source to share
A question of convention. Distinguishes between the organization of the organization. Previously, we were asked not to be bothered by commenting on getters and setters as long as it's obvious what it is doing. Same as comments without {@link}
.
We are currently adding {@link}
as the previously written codes already have this convention.
source to share
If you can reference #auto_key
using in your documentation {@link}
, it means the variable is public (otherwise the reference will not be resolved in the javadoc). This means the getter and setter are redundant.
I highly recommend making your field auto_key
private and keeping the getter and setter. Then adjust the recipient's name and setter in accordance with the agreements Java ( autoKey
, setAutoKey
, getAutoKey
). And consider shooting PropertyChangeEvent
when changes autoKey
(as a getter / setter combination is commonly used - see JavaBeans ).
As far as your documentation goes: it doesn't add anything new to what the method name already suggests. So I would remove it, or add additional documentation on what exactly does autoKey
(which is not clear to me from the snippet) whether it can be set to null
, ....
source to share