Documenting getters and setters [closed]

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?

Answer 1

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#)

Answer 2

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).

Answer 3

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.