对于简单的 getter/setter，如下所示，记录它的最佳方式是什么？
public float getPrice()
{
return price;
}
我对编码标准非常严格，所以我的 IDE 会警告我任何未记录的公共/受保护方法。
选项 1：
/**
* Get the price field.
*
* @return
*/
选项 2：
/**
* @return Price
*/
或者根本不记录？
【问题讨论】：
标签： language-agnostic documentation coding-style javadoc
如果“价格”不是最明显的值，那么您的评论应该描述“价格”的含义和用途，而不仅仅是它的名称。
一些假设的例子：
对于大部分方法和属性，您可以说一些东西告诉读者，而不仅仅是名称会告诉他们。这将为其他程序员节省大量时间并降低出现错误的风险。即使它只是证实了他们的猜测/假设，它仍然可以节省他们的时间。
对于完全不言自明的“简单”值（例如 Rectangle.Width），请不要浪费您的时间输入 - AtomineerUtils 将通过一次按键为您创建该级别的文档。 （在您的案例中，AtomineerUtils 的优势在于它支持 Doxygen、Javadoc 和 Documentation XML 注释格式，以及 VB、C#、C++/CLI、C++ 和 C 代码，因此您可以保留现有格式，同时大量减少您花在文档注释。GhostDoc 会做类似的工作，但它只支持 VB 和 C# 的 Xml 文档）
【讨论】：
我会写下最低限度的代码以保持 linter 安静。如果 getter/setter 获取/设置的内容很明显，我会使用一些复制粘贴文档来明确说明没有任何花哨的事情发生：
/**
* Simple getter.
* @return Price
*/
我个人认为太多的 getter 和 setter 是代码异味，因为这可能表明您没有在正确的抽象级别上提供操作（这显然并不总是正确的，而是一个经验法则）。
【讨论】：
描述另一个程序员理解该方法的作用或返回的最低要求。
我会用这个：
/**
* @return the price.
*/
或
/**
* Returns the prize.
*
* @return the price.
*/
这复制了相同的文本，但如果您同意某些需要描述而不仅仅是标签的编码标准，则可能有必要。
我不会提到它返回价格字段，因为它描述了内部表示。
【讨论】：
记录界面，就好像用户对实现一无所知。文档适用于方法的调用者，他们不必知道或关心特定的内部状态是什么，但必须关心方法为他们做了什么。
【讨论】：
我一直在寻找一种标准的方式来实现 doco 函数，直到我搜索 SO 并发现人们使用： GhostDoc - http://submain.com/products/ghostdoc.aspx
它是目前最好的自动 doco 工具之一，并以相同的方式格式化每个 cmets。最好的一点是，如果您的方法被恰当地命名，那么您甚至不需要编辑自动生成的文档，因为它是有意义的。
此外，当您使用智能感知时，cmets 会出现，因此您可以在编写代码一个月后提醒您代码做了什么！ :)
GhostDocs 将对您的属性执行此操作：（快捷键 Ctrl+Shift+D）
/// <summary>
/// Gets the price.
/// </summary>
/// <returns></returns>
public float getPrice()
{
return price;
}
【讨论】：