setter 和 getter 方法的默认注释

Question

在代码审查期间，我们正在讨论代码注释部分。我们的一位团队成员建议对所有 setter/getter 方法添加默认注释。它们真的有用吗？如果是，那么放置默认注释有什么用。

/**
     * @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;
    }

谢谢:)

Answer 1

拜托，不要那样做，鲍勃叔叔会永远诅咒你。阅读这篇文章： http://blog.cleancoder.com/uncle-bob/2017/02/23/NecessaryComments.html

也许读这本书：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

重点是：注释对代码的理解增加了什么？？如果代码不能按原样理解，则需要将其编写得更好。但是 getBanana 方法确实需要像 "returns a Banana?" 这样的注释。

还有，如果以后改了代码，方法变成了getFruit，但是忘了改注释怎么办？下一个阅读它的开发人员会感到困惑。

真的，帮自己一个忙：不要添加无用的评论。即使它们是自动的。

Answer 2

没有对错之分，见仁见智。

但就我个人而言，我认为对 getter 或 setter 的评论是多余的，因为这种方法的作用通常很明显。除非它有某种副作用或特殊情况，否则您认为注释真的会向 getter/setter 方法添加任何信息吗？

在此示例中，setBuildType 设置对象的构建类型，这从方法名称和方法的快速扫描中显而易见。真的需要多占三行竖屏space解释一下吗？

假设 setBuildType 方法有副作用，当您设置构建类型时，它会更改对象中的其他变量，或者根据您设置的构建类型调用其他方法，然后可能是评论解释这些副作用对使用该方法的用户很有用。

Answer 3

根据软件开发的最佳实践，编码良好的软件不需要注释。但有时与客户签订的合同可能需要对每种方法或 class 进行记录。在这种情况下，您甚至需要默认注释。

Answer 4

没有必要在您的模型中添加注释，建议属性名称简明扼要。一个很好的优势是您还将获得更清晰的代码。作为开发人员，您的 objective 应该尽可能清楚地让其他人轻松理解其目的，而不会用评论压倒他们。

通常，您将注释放在 controllers/services/logical 条件上，而不是在模型中。

我在其他企业应用程序中也没有看到这种做法，所以我的看法是您不必这样做，相反我会专注于技术文档以 state/explain 每个属性和其他属性的责任重要细节。

setter 和 getter 方法的默认注释

Default comment on setter and getter methods

java

pojo