Default comment on setter and getter methods

Question

During code review we are discussing on code comment part. One of our team member suggest to put default comment on all setter/getter methods. Are they really useful if yes then what are the use of putting default comments.

/**
     * @param name the name to set
     */
    public void setName(String name) {
        this.name = name;
    }

    /**
     * @return the billType
     */
    public BillType getBillType() {
        return billType;
    }

    /**
     * @param billType the billType to set
     */
    public void setBillType(BillType billType) {
        this.billType = billType;
    }

    /**
     * @return the lateCharge
     */
    public Float getLateCharge() {
        return lateCharge;
    }

    /**
     * @param lateCharge the lateCharge to set
     */
    public void setLateCharge(Float lateCharge) {
        this.lateCharge = lateCharge;
    }

    /**
     * @return the lateChargeType
     */
    public LateChargesType getLateChargeType() {
        return lateChargeType;
    }

    /**
     * @param lateChargeType the lateChargeType to set
     */
    public void setLateChargeType(LateChargesType lateChargeType) {
        this.lateChargeType = lateChargeType;
    }

    /**
     * @return the billDay
     */
    public String getBillDay() {
        return billDay;
    }

Thanks :)

Answer 1

There is no right or wrong answer, this is a matter of opinion.

Personally though, I think comments on a getter or setter are redundant, as it's usually pretty obvious what such a method does. Unless it has some sort of side effects or special case, do you think a comment really adds any information to a getter/setter method?

In this example, setBuildType sets the build type of the object, this is obvious from the method name and from a quick scan of the method. Do you really need to take up an extra three lines of vertical screen space explaining it?

Let's say the setBuildType method had side effects, and when you set the build type it changes other variables in your object, or calls into other methods based on the build type you set, then perhaps a comment explaining these side effects would be useful for users of the method.

Answer 2

please, don't do that, uncle bob would damn you for the eternity. read this article: http://blog.cleancoder.com/uncle-bob/2017/02/23/NecessaryComments.html

and maybe read this book: https://www.amazon.co.uk/dp/0132350882/ref=as_at?slotNum=2&ie=UTF8&linkCode=g12&linkId=OE6W2DLW3J5Z2TNZ&imprToken=XmYYGuMNIMkg8-pwYK0HdQ&creativeASIN=0132350882%3FslotNum%3D2%26ie%3DUTF8&tag=simplprogr0e-21&creative=390957&camp=1789

The point is: what does the comment add to the understanding of the code?? If the code is not understandable as it is, you need to write it better. But a getBanana method, does really need a comment like "returns a Banana?".

Also, what if in the future you change the code and the method becomes getFruit, but you forget to change the comment? The next developer that would read it would be confused.

Really, do yourself a favour: don't add useless comments. Even if they are automatic.

Answer 3

According to the best practices of software development a well coded software does not need comments. But sometimes a contract with a client may require documentation over every method or class. In such cases you need even the default comment.

Answer 4

It's not necessary to put comments in your model and would suggest to make the property names clear and concise. A very good advantage is you will also obtain cleaner code. Your objective as a developer is to make it as clear as possible for others to easily understand the purpose without overwhelming them with comments.

Normally, you put the comment on the controllers/services/logical conditions, but not in the models.

I also don't see this kind of practice in other enterprise applications so my take is you don't have to and instead I would focus on technical documentation to state/explain the responsibility of each properties and other important details.