Java comment for getter and setter method

Question

my question is should i comment like 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 comment for getter and setter method is correct? or should i use normal comment without using {@link}? and this way is a java standard or not?

Answer 1

Actually, I deliberately don't javadoc getters and setters, because you aren't adding any value by doing so - they are what they are... accessor methods. In fact, you would be creating a kind of code bloat by adding javadoc to them.

I only put javadoc on non-getter/setters.

Answer 2

1. I would suggest generating stand-alone documentation for your set/get methods, while still using {@link} , that is to do both. This way, when the field is accessible people can still get to its documentation. If afterwards it becomes private due to a refactoring, you won't end-up with a bunch of incomplete Javadocs that need to be modified as well.

2. While documentation for setter/getter methods may seem like code bloat, I would still suggest creating it for a couple of reasons:

   • It gives you a standard location to mention important information, such as setter arguments that should not be null or getters that are woefully inefficient in a particular implementation of an interface.

   • It does not assume that the reader automatically knows what the backing field does. Sure, setLength() may be descriptive enough in some contexts, but what exactly does setLimit() do?

   • It does not assume that there is a backing field, or that the get/set methods are only doing just that in a particular implementation. It is an unfortunate reality that when refactoring is constrained by compatibility concerns, various artifacts are left behind. Eg setLimit() could delegate to setSizeLimit() , which is something that should be noted.

   • It removes any and all ambiguity. What you consider to be common-sense may not be straight-forward for all people. Without documentation various assumptions will be made that may or may not be true. For example, in a list implementation, does setLength(0) also set all contained references to null or not?

   • Most importantly, it allows the Javadoc policy to boil-down to a simple "document everything everywhere". Having a policy with various exceptions, on the other hand, will inevitably lead to laxness and code that is eventually left undocumented.

Answer 3

Matter of convention. Varies organization to organization. Previously, we were asked not bother commenting on getters and setters as long as it is obvious what it does. Which is same as comments without {@link} .

Currently, we add {@link} as codes written earlier already has this convention.

Answer 4

If you can refer in your documentation to #auto_key using the {@link} , it means the variable is public accessible (otherwise, the link would not resolve in the javadoc). This means the getter and setter are redundant.

I would strongly recommend to make your auto_key field private and keep the getter and setter. Then adjust the name of the getter and setter to match Java conventions ( autoKey , setAutoKey , getAutoKey ). And consider firing PropertyChangeEvent s when the autoKey is changed (as a getter/setter combination typically suggests - see JavaBeans ).

As for your documentation: it adds nothing new to what the name of the method already suggests. So I would remove it, or add some extra documentation on what the autoKey exactly does (which is not clear to me from the snippet), whether it may be set to null , ... .

Answer 5

You should not put any comments describing getters or setters, unless the method looks like one, but encapsulated different behaviour.

Answer 6

Accessors and mutators are generic methods in classes where the notion of encapsulation is applied (ie having private instance attributes). This is why in some IDEs like Netbeans for example, they can even be generated automatically.

Also, their names, according to conventions, are quite explicit about what they do and thus allow to distinguish them from other methods more specific to business needs.

All this to say that they do not need to be documented.

Of course, if in the context of your application you add a particular instruction in >your setter for example, in relation to your needs and the logic of your program, in my >opinion, nothing prevents you from adding a descriptive comment line to it