6

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/… – Dylan Meeus Dec 24 '14 at 15:29
  • @DylanMeeus excellent exactly what I was looking for. Therefore my javadoc example is correct – benscabbia Dec 24 '14 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 '14 at 15:33
  • 1
    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 '14 at 15:56
  • @Snowman I was unaware of that, thanks for the info! – benscabbia Dec 24 '14 at 16:08
4

Private fields are usually ignored by documentation tools, so when you ship your API to a third party, he/she 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 IDE's 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 '14 at 15:34
  • 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. – Andrew T Finnell Aug 16 '18 at 19:46

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

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