language-agnostic - 记录 getter 和 setter

Question

关闭。这个问题是opinion-based .它目前不接受答案。












想改进这个问题？更新问题，以便 editing this post 可以用事实和引用来回答它.

4年前关闭。




Improve this question




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

public float getPrice()
{
    return price;
}

我对编码标准非常严格，所以我的 IDE 会警告我任何未记录的公共(public)/ protected 方法。

选项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 文档)