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

没有正确或错误的答案，这是一个意见问题。

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

在此示例中，setBuildType设置了对象的构建类型，这从方法名称和方法的快速扫描中很明显。你真的需要占用额外的三行垂直屏幕空间来解释它吗？

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

Answer 2

请不要这样做，叔叔鲍勃会诅咒你永恒。阅读这篇文章： 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方法确实需要一个像＃34;返回香蕉的评论？＆＃34;。

此外，如果您将来更改代码并且方法变为getFruit，但您忘记更改注释，该怎么办？下一个读它的开发人员会感到困惑。

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

Answer 3

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

Answer 4

没有必要在您的模型中添加评论，并建议使属性名称清晰简洁。一个非常好的优点是您还将获得更清晰的代码。您作为开发人员的目标是让其他人尽可能清楚地了解其目的，而不会用评论来压倒他们。

通常，您将注释放在控制器/服务/逻辑条件上，但不在模型中。

我也没有在其他企业应用程序中看到这种做法，所以我的看法是你不必，而是我将专注于技术文档来陈述/解释每个属性的责任和其他重要细节。

对setter和getter方法的默认注释

4 个答案: