Question

对于简单的getter / setter，如下所示，记录它的最佳方法是什么？

public float getPrice()
{
    return price;
}

我对编码标准非常严格，因此我的IDE会警告我任何未记录的公共/受保护方法。

选项1：

/**
 * Get the price field.
 * 
 * @return
 */

选项2：

/**
 * @return Price
 */

或者根本不记录它？

Answer 1

如果“价格”不是最明显的价值，那么你的评论应该描述“价格”的含义和用途，而不仅仅是它的名称。

一些假设的例子：

是“税前价格”还是“含税价格”？
是以美元，欧元还是英镑表示？
是四舍五入到最接近的分数，5美分还是美元？
是否返回一个特殊值来表示免费项目（例如0.0f）？
价格是否可以“未初始化”，如果是，则返回什么值（例如-1.0f）？

对于很大比例的方法和属性，你可以说可以告诉读者不仅仅是名字会告诉他们。这将为其他程序员节省大量时间并降低错误风险。即使它只是证实了他们的猜测/假设，它仍然会节省他们的时间。

对于完全不言自明的“简单”值（例如Rectangle.Width），请不要浪费时间输入 - AtomineerUtils将通过单个按键为您创建该级别的文档。（在您的情况下，AtomineerUtils的优势在于它支持Doxygen，Javadoc和Documentation XML注释格式，以及VB，C＃，C ++ / CLI，C ++和C代码，因此您可以保留现有格式，同时大幅减少花费的时间文档评论.GhostDoc将做类似的工作，但它只支持VB和C＃的Xml文档。

Answer 2

我写了最低限度以保持linter安静。如果getter / setter获取/设置的内容很明显，我会使用一些复制粘贴文档，清楚地表明没有任何花哨的东西：

/**
 * Simple getter.
 * @return Price
 */

我个人认为太多的getter和setter是代码气味，因为它可能表明你没有在正确的抽象级别提供操作（这显然并非总是如此，而是经验法则）。

Answer 3

描述另一个程序员理解该方法的作用或返回的最小值。

我会用这个：

/**
 * @return the price.
 */

或

/**
 * Returns the prize.
 *
 * @return the price.
 */

这会复制相同的文本，但如果您同意某些需要说明而不仅仅是标记的编码标准，则可能需要这样做。

我不会提到它返回价格字段，因为它描述了内部表示。

Answer 4

记录界面，就好像用户对实现一无所知。文档适用于方法的调用者，他们不必知道或关心特定的内部状态，但是必须关心方法对他们的作用。

Answer 5

我一直在寻找doco功能的标准方法，直到我搜索SO并发现人们使用： GhostDoc - http://submain.com/products/ghostdoc.aspx

它是最好的自动doco工具之一，并以同样的方式格式化每个评论。关于它的最好的事情是如果你的方法被恰当地命名，那么你甚至不需要编辑自动生成的doco，因为它是有意义的。

此外，当您使用intellisense时会出现注释，因此您可以在编写代码后的一个月内提醒您注意代码的作用！：）

GhostDocs将对您的属性执行此操作:(快捷键Ctrl + Shift + D）

    /// <summary>
    /// Gets the price.
    /// </summary>
    /// <returns></returns>
    public float getPrice()
    {
        return price;
    }

记录getter和setter

5 个答案: