Recipient and Setter Documentation

Question

For simple getters / seters as shown below, what's the best way to document it?

public float getPrice() { return price; } 

I'm pretty strict on coding standards, so my IDE warns me of any undocumented public / secure methods.

Option 1:

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

Option 2:

 /** * @return Price */ 

Or not document it at all?

Answer 1

I would write a minimum minimum to keep the lint quiet. If it is obvious that get / setter receives / sets, I would use some documentation for copy-paste, which makes it clear that nothing unusual is happening:

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

I personally consider too many getters and setters to have code smells, as this is a possible sign that you are not performing operations at the right level of abstraction (this, obviously, is not always true, but a rule of thumb).

Answer 2

If “price” is something other than the most obvious meaning, then your comment should describe what “price” means and is used, and not just what it is called.

Some hypothetical examples:

• Is it a “pre-tax price” or a “price including tax”?
• Is it expressed in dollars, euros or pounds?
• Is it rounded to the nearest cent, 5 cents or dollars?
• Is this a special value returned to indicate a free element (e.g. 0.0f)?
• Can the price be “uninitialized”, and if so, what value is returned (for example, -1.0f)?

For a good proportion of methods and properties, you can say that tells the reader more than just the name will tell them. This will save other programmers a lot of time and reduce the risk of errors. Even if he simply confirms his assumptions / assumptions, he will still save their time.

In the case of “simple” values ​​that do not require any explanation (for example, Rectangle.Width), then do not waste your time typing - AtomineerUtils will create this documentation level for you with one click. (The advantage of AtomineerUtils in your case is that it supports XML comment formats Doxygen, Javadoc and Documentation and VB, C #, C ++ / CLI, C ++ and C, so you can save your existing format in the same time to significantly reduce the time spent commenting documentation GhostDoc will do a similar task, but it only supports Xml documentation for VB and C #)

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 may be required if you agree with some coding standards that require a description, not just tags.

I would not say that it returns a price field since it describes the internal representation.

Answer 4

Document the interface as if the user knew nothing about the implementation. Documents are intended for callers of the method who do not need to know or care about what a particular internal state is, but keep in mind what the method does for them.

Answer 5

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

This is one of the best auto dock tools and formats each of your comments in the same way. The best thing about this is that your methods are aptly named, then you don’t even need to edit the automatically generated doco, as that would make sense.

In addition, comments appear when you use intellisense so you can remember what your code does a month after you write it! :)

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

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