Language agnostic 记录getter和setter

对于简单的getter/setter，如下面的一个，记录它的最佳方式是什么

public float getPrice()
{
    return price;
}

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

备选案文1：

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

备选案文2：

/**
 * @return Price
 */

---

或者根本不记录它？

我会写最低限度，以保持过梁安静。如果很明显getter/setter正在获取/设置什么，我会使用一些复制粘贴文档来明确说明没有什么特别之处：

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

---

<> P>我个人认为太多的吸收者和设置者是代码嗅觉，因为这是一个可能的迹象，表明你没有在正确的抽象层次上提供操作（显然这不是真的，而是经验法则）。这些文档是为方法的调用者准备的，他们不必知道或关心具体的内部状态是什么，但必须关心方法为他们做了什么。

我一直在寻找doco函数的标准方法，直到我搜索了它，发现有人使用： 幽灵医生-

它是最好的auto doco工具之一，可以用同样的方式格式化您的每条评论。最好的一点是，如果你的方法被恰当地命名，那么你甚至不需要编辑自动生成的文档，因为这是有意义的

此外，当您使用intellisense时，会出现注释，这样您就可以在编写代码一个月后提醒您代码的功能了！：）

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

//
///得到价格。
/// 
/// 
公开发行价格（）
{
退货价格；
}

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

我会用这个：

/**
 * @return the price.
 */

或

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

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

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

一些假设的例子：

• 是“税前价格”还是“含税价格”
• 它是用美元、欧元还是英镑表示的
• 是四舍五入到最接近的美分、5美分还是美元
• 是否返回一个特殊值以指示自由项（例如0.0f）
• 价格是否可以“未初始化”，如果是，返回什么值（例如-1.0f）

对于大部分的方法和属性，您可以说的不仅仅是名称告诉读者。这将为其他程序节省大量时间，并降低出现bug的风险。即使这仅仅证实了他们的猜测/假设，也会为他们节省时间

---

对于完全自解释的“简单”值（例如，Rectangle.Width），则不要浪费时间键入-只需按一次键即可为您创建该级别的文档。在您的情况下，AdoxNeURTILS的优点是它支持doxEngy、JavaDoc和文档XML注释格式，以及VB、C++、C++/CLI、C++和C代码，这样您可以保留现有格式，同时大大减少文档注释时所花费的时间。GhostDoc将执行类似的工作，但它只支持VB的XML文档。而C#）

GhostDoc不支持Javadoc。啊，是的，愚蠢的我错过了Javadoc标记。它只对可视化研究有用可能的重复

/**
 * @return the price.
 */

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