Documenting properties

When deciding what to document and how, remember that documentation should have an audience. If you cannot define the audience, then why are you documenting anything?

So, that's step 1: what is your audience?

One of the options, to document the property, is a no-brainer in most situations. Properties are implementation details that are useless outside of the current class. Don't document properties... until the class gets big enough that it becomes useful for the maintainers of that class — an audience!

Typically we document things that other programmers will find interesting or relevant. Public and protected members of a class are more typically documented. I advocate for not documenting things that are obvious. If you are merely repeating words in the javadoc comment that already exist on the class, method name, return type, parameter types, or parameter names, I am loathe to write any documentation for a method or property at all. Names mean something. People should be making assumptions based on the names of things, and if the assumption was wrong then rename the thing.

That being said, I also work with people who never read the names of things and instead only rely on the auto-complete suggestions in their IDE. Yup. I can name a method blargityFloogenBlork and it would pass code review as long as I give it a good javadoc comment.

I admit, that was a bit of a rant, but you also need to know your team. Documentation is for humans, and humans are notoriously fickle about random things.

If writing a javadoc comment serves the human, then write it. If it only serves as a box-ticking exercise, then don't write it. Force your team to tell you why it's necessary beyond "that's how we do things" because only then will you know your audience, and only then will you know what is worth documenting.

Where should I describe the property?

With its name.

If the name describes the property adequately please spare me redundant java docs.

If the name doesn't, then fix the name.

If for some reason you just can't think of a good name that eliminates the java doc:

• Rethink the design of this property. Might be too complicated.
• Put the java doc on whatever part is making it complicated. Be it the getter, setter, or var.

But seriously, I'd rather have a good name.

Your question doesn't make it clear but from the comments you have given on other answers, I think I have an idea what you are trying to do. First, along the lines of the other answers, what you shouldn't do:

/** the foo */ private String foo; /** gets the foo */ String getFoo() { return this.foo; } /** sets the foo */ void setFoo(final String foo) { return this.foo = foo; } 

I've seen this kind of thing too much. It's just noise.

But I don't think that's what you are asking about. What I think you are talking about is documenting the meaning, purpose, and allowed values of your foos. If the class is Person, and the property is firstName, then you probably don't need to document this at all. It's obvious what firstName is. However, sometimes the property name is not enough information.

Not java, but I came upon this recently when trying to solve a problem. I think it demonstrates the issue you are trying to solve. A lot of those parameter names have fairly obvious meanings such as: user, password, host, port. I don't really need any additional information about those. But purity, matchanytag? Not obvious. use_tcp_fast_open sounds good but what are the implications of using it? Why does it default to False? There's no documentation on this method. But if you continue down the page, there is a paragraph or so for many (but not all) of the properties/fields.

So if you are talking about something like this, I think there are a few options. I wouldn't document on the getter or setter. You might be tempted to put the javadocs on the field instead but IIRC, private fields don't appear in JavaDocs by default. You could use the -private switch on Javadoc but I think that will show all private members on every class (I'm not 100% sure on that.)

One option that you might want to consider is putting a long-form explanation in the class JavaDoc. You could add a list of the properties and add commentary about any non-obvious details about the properties. You could also simply provide those details in another html page somewhere but I would at least add a link to that in the class JavaDocs so it's easy to locate (until it is moved and no one bothers to update the link)

I do not much document private fields though coding details like "depends on other field y being null; is cached".

Java doc for the users, getter and setter are important for the javadoc popups. Getters probably more often, and are written for the task at hand (get/set). Things like "statefull, mutable, may be stale".

The interesting documentation, more on the behaviour, usage, related to business logic, fits better on class level. Code snippets in javadoc of a class explaining specific things might be more useful. While coding one would steal such a snippet. As opposed to self designing a piece of code and the calling tentative a getter (then seeing its javadoc). A constructor might be appropriate. Unit tests can partly serve as code snippets.

Of course besides javadoc there can be room reserved for more story like documentation of business logic and use cases; versioned and code linked.

To make that all without too much repetition, access is important, like javadoc links, @see, so one can click in one javadoc popup and for instance jump from setter to getter to constructor to code snippet.

This all only works if the effort is not large, minimal, and there is sufficient "show off" potential (reviewing). Look at existing code and start redoing the documentation to get something interesting. In an ideal world one would have PFD export of technical documentation, but at least one can a demo project for documentation. Documentation on documentation.