Documenting getters and setters [closed]

Closed. This question is opinion-based. It is not currently accepting answers. 开发者_开发知识库

---

Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.

Closed 4 years ago.

Improve this question

For simple getters/setters, like the one below, what's the best way to document it?

public float getPrice()
{
    return price;
}

I'm pretty strict about coding standards, so my IDE warns me about any undocumented public/protected methods.

Option 1:

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

Option 2:

/**
 * @return Price
 */

Or don't document it at all?

---

If "price" is anything other than the most obvious value, then your comment should describe what "Price" means and is used for, not just what it is called.

Some hypothetical examples:

• Is it the "price before tax" or the "price including tax"?
• Is it expressed in dollars, euros or pounds?
• Is it rounded to the nearest cent, 5 cents, or dollars?
• Is a special value returned to indicate a free item (e.g. 0.0f)?
• Can a price be "uninitialised", and if so, what value is returned (e.g. -1.0f)?

For a good proportion of methods and properties, there is something you can say that tells the reader more than just the name will tell them. That will save other progammers a lot of time and reduce the risk of bugs. Even if it merely confirms their guesses/assumptions, it will still save them time.

In the case of "simple" values that are totally self-explanatory (e.g. Rectangle.Width), then don't waste your time typing - AtomineerUtils will create that level of documentation for you with a single keypress. (The advantage of AtomineerUtils in your case is that it supports Doxygen, Javadoc and Documentation XML comment formats, and VB, C#, C++/CLI, C++ and C code, so you can retain your existing format while massively reducing the time you spend on documentation commenting. GhostDoc will do a similar job, but it only supports Xml documentation for VB and C#)

---

I'd write the bare minimum to keep the linter quiet. If it's obvious what the getter/setter is getting/setting, I'd use some copy-paste documentation that makes it clear that nothing fancy is going on:

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

I personally consider too many getters and setters to be a code smell, as it's a possible sign that you're not providing operations at the correct level of abstraction (this is obviously not always true, but a rule of thumb).

---

Describe the minimum for another programmer to understand what the method does or returns.

I would use this:

/**
 * @return the price.
 */

or

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

This duplicates the same text, but a it might be necessary if you agreed on certain coding standards that require a description and not only the tags.

I would not mention that it returns the price field, since that describes the internal representation.

---

Document the interface as if the user knew nothing about the implementation. The docs are for callers of the method, who don't have to know or care what the specific internal state is, but do have to care what the method does for them.

---

I was looking for a standard way to doco functions until i searched SO and found people using: GhostDoc - http://submain.com/products/ghostdoc.aspx

It's one of the best auto doco tools out there and formats each of your comments the same way. The best thing about it is if your methods are aptly named, then you don't even need to edit the auto-generated doco as it will make sense.

Also, the comments comes up when you use intellisense so you can be reminded of what your code does a month after you've written it! :)

GhostDocs will do this to your property: (shortcut Ctrl+Shift+D)

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