Whom do I talk to in Javadocs? [closed]

Question

Closed. This question is opinion-based. It is not currently accepting answers.

---

Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.

Closed 5 years ago.

Improve this question

I am currently working on an uni assignment. We have to write Javadoc comments. My problem is that I don't really know to whom I'm "talking" here.

Some examples for comments to different methods in my project:

• "The next thing we care about is the number of..."
• "We want to remove those items from the list because..."

So the questions is: can i put Javadocs like that or do I have to write them in formal language? And who do I adress in my sentences (if I can adress someone).

Answer 1

It's entirely up to you / your team how formal or informal to make your Javadoc.

It's relatively rare to directly address anyone (either with "you" or "we"), but again, it's your call. Consider the JDK's docs, which typically go something like this:

The String class represents character strings. All string literals in Java programs, such as "abc", are implemented as instances of this class.

Direct, clear, and impersonal. Just state the facts.

Another example (from Object#equals):

Note that it is generally necessary to override the hashCode method whenever this method is overridden, so as to maintain the general contract for the hashCode method, which states that equal objects must have equal hash codes.

Notice how it didn't say "Note that you must generally override..." It doesn't tell anyone what to do, just notes that if doing X, generally it's necessary to do Y.

Answer 2

Javadocs matter most if you're publishing to third parties. You won't be present to expound on your code. Third parties will want to just use your classes wo/ worrying about how they fulfill their contract. Your documentation should tell them what they need to know: what the terms of the contract is. They need to know what to provide, what to expect back, exceptions, invariants, etc.

I would say keep the language formal in that case. It reflects better on you.

You don't communicate with third parties the same way you do your friends. Better to keep it formal.

I would stop using "we" and think more in terms of "you". It's about the consumer of your library, not the developers.