记录getter和setter[关闭]

我写了最起码的一个字来保持门楣的安静。如果很明显getter/setter正在获取/设置什么,那么我将使用一些复制粘贴文档来清楚地表明没有发生任何幻想:

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

我个人认为太多的getter和setter不可能是代码味道,因为这可能表明您没有在正确的抽象级别上提供操作(这显然不总是正确的,但是一个经验法则)。

如果“价格”不是最明显的值,那么您的评论应该描述“价格”的含义和用途,而不仅仅是它被称为什么。

一些假设的例子:

• 是“税前价格”还是“含税价格”?
• 它是用美元、欧元还是英镑表示的?
• 是四舍五入到最接近的分、5分还是美元?
• 是否返回一个特殊值来表示一个自由项(例如0.0f)?
• 价格是否“未初始化”,如果是,返回的值是多少(例如-1.0f)?

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

如果“简单”值是完全不需要解释的(例如rectangle.width),那么不要浪费时间键入- AtomineerUtils 将用一个键为您创建该级别的文档。在您的情况下,AddieNeURTILS的优点在于它支持DOXYGEN、JavaDoc和文档XML注释格式,以及VB、C、C++、CLI、C++和C代码,因此您可以保留现有格式,同时大大减少在文档注释上花费的时间。GhostDoc也会做类似的工作,但它只支持用于vb和c的XML文档

请描述另一个程序员了解该方法执行或返回操作的最小值。

我会用这个:

/**
 * @return the price.
 */

或

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

这复制了相同的文本,但如果您同意某些需要描述的编码标准,而不仅仅是标签,则可能有必要这样做。

我不想提它会退货 领域 ,因为这描述了内部表示。

记录接口,就好像用户对实现一无所知一样。文档是为方法的调用者准备的,这些调用者不必知道或关心特定的内部状态是什么,但必须关心方法为他们做了什么。

我一直在寻找一种标准的doco函数方法,直到我搜索了它,发现人们使用: 鬼魂- http://submain.com/products/ghostdoc.aspx

它是目前最好的自动文档工具之一,并以相同的方式对每条评论进行格式化。最好的一点是,如果您的方法命名恰当,那么您甚至不需要编辑自动生成的doco,因为它是有意义的。

另外,当您使用IntelliSense时,注释会出现,这样您就可以在编写代码后一个月提醒您代码的功能了!:)

ghostdocs将对您的属性执行此操作:(快捷方式ctrl+shift+d)

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