This is a really simple question but oddly, I'm finding it difficult to get a definite answer....

What do you do with fields? Is this valid?

 * Keeps track of all usernames in the system.
private List<String> usernames = new ArrayList<>();

Or is above ingnored by documentation tools, so would it be best to do something like:

 //Keeps track of all usernames in the system.   
private List<String> usernames = new ArrayList<>();

Since (from what I see), documentation only shows methods, constructors and classes, what do programmers usually do with fields?

  • 1
    This is probably what you are looking for: stackoverflow.com/questions/2273170/… Dec 24, 2014 at 15:29
  • @DylanMeeus excellent exactly what I was looking for. Therefore my javadoc example is correct
    – benscabbia
    Dec 24, 2014 at 15:31
  • "The Javadoc tool can generate output originating from four different types of "source" files: Source code files for Java classes (.java) - these contain class, interface, field, constructor and method comments..." (SO tag wiki -> How to Write Doc Comments for the Javadoc Tool)
    – gnat
    Dec 24, 2014 at 15:33
  • 2
    You can have the brevity of example 2 and the benefits of example 1 by using a single-line JavaDoc: /** Keeps track of all usernames in the system. */
    – user22815
    Dec 24, 2014 at 15:56
  • @Snowman I was unaware of that, thanks for the info!
    – benscabbia
    Dec 24, 2014 at 16:08

1 Answer 1


Private fields are usually ignored by documentation tools, so when you ship your API to a third party, they will not be able to see any documentation regarding private fields (unless you specify that you also want to include private fields in the documentation during the documentation generation phase of your project).

That being said, I think it is a good idea to use JavaDoc to also document private fields because:

  • It will conform to the rest of the other documentation.
  • Most IDEs will extract JavaDoc and show it to you when you try and access different object properties. This can save time going around the code to see what is the purpose of a particular variable.
  • In the event that you will want to include private field documentation into your documentation, all the work will have already been done.
  • thanks for the answer. My gut feeling was to use JavaDoc but I was unsure due to Private fields are usually ignored by documentation tools. (I will accept ASAP)
    – benscabbia
    Dec 24, 2014 at 15:34
  • 1
    None of those reasons are pragmatic nor useful reasons to do something. Doing something just because other places do it that way is a very poor reason to do it. Documentation just to meet guidelines that provides no value seems like a waste. Places seem to go overboard with javadoc's or never do it. The happy medium is the best. Aug 16, 2018 at 19:46

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.