63

Should I write JavaDoc for private or protected methods? And what about private variables?

I see class examples on my Java book and the private variables are JavaDoc'ed. So I can't understand if it is a good practice to JavaDoc the private (or protected) methods.

Improve this question
2
  • 14
    You should write comments for anything that isn't obvious. Commented Feb 7, 2014 at 15:50
  • 1
    In your javadocs on private/protected methods will show up if you use the show javadocs command in your IDE (at least Intellij). In line comments will not. That's one practical benefit to javadocs instead of inline comments when description beyond the method signature is useful. Commented Feb 21, 2017 at 18:26

5 Answers 5

Reset to default
72

Yes you should write JavaDoc for private methods, and even when it is only for yourself. In 3 years when you have to change the code, you will be happy that you documented it.

If you leave the company, or have to work on another project, your co-workers will be happy to have a documented code. Undocumented code has much lower value.

And look how the real professionals do it. Here is an excerpt from the source code of ArrayList class by Sun Microsystems:

 /**
  * The array buffer into which the elements of the ArrayList are stored.
  * The capacity of the ArrayList is the length of this array buffer.
  */
  private transient Object[] elementData;
Improve this answer
Sign up to request clarification or add additional context in comments.

15 Comments

Does public HelloWorld() {system.out.println("Hello World")} have less value than //prints Hello World HelloWorld() {system.out.println("Hello World")}?
We dont talk of one line well known Hello world coede. In professional development undocumnetd code cause higher costs for the next person that work on that code. And even if it's your own code, some years after creating you loose more time thinking why and what, than the costs of documenting at time of creation fly.
The question clearly is about JAVADOC. As the answer of ashes999 states, Javadoc is primarily for the people who consume your code. You're talking about COMMENTING your code and what you're saying is valid and I'm on the same path, but this doesn't count for javadoc. Javadoc isn't designed to keep your comments for yourself and your coworkers and get them out in the public for all your consumers.
@testuser to your comment: "javadoc isn't designed to keep your comments..." Javadoc has a feature, that let you create the javadoc html for only public methods/fields. So write the private for yourself and publish only the public ones for the consumers, if there is some necessity to supress info.
@testuser, No, The option "public only" is the default option. And further it seems that you don't know javadoc, so think yourself whether it makes sense to continue this discussion.
|
46

The first question you need to ask yourself is "why write JavaDocs at all?" Who are they useful for? Who asked you to write them?

Most likely, someone (employer / professor) asked you to document some of your methods. This is generally A Good Thing, but comes with a cost: additional maintenance.

If you have a publicly accessible version of your docs (such as if you're generating them and publishing them online for end-users), it makes sense to document anything your end users will need to know. This includes all public classes and methods.

What about for yourself, and other developers?

My opinion is that you shouldn't use javadocs on internal and private methods and classes. The main reason is that javadocs primarily benefit people who consume, not maintain, your code.

On the other hand, you do need to keep notes and comments on your own code, which is often internal. In this case, I would suggest normal comments (eg. //) instead; it's less maintenance, and often, equally clear, with a lot less typing.

On the other hand, if a method becomes public, it can be useful to convert those comments into a true javadocs. Javadocs have the benefit of forcing you to think about (and document) every parameter, exception, and return value.

The trade-off is yours to make.

Improve this answer

9 Comments

FYI, for .NET developers, Visual Studio shows these comments when you hover your mouse over a method name -- even for private methods -- so for .NET code, it makes sense to do this.
Eclipse does the same, it's a very beneficial feature.
I don't see why "//" is less maintenance that "/**". And practically using "//" is more typing, because eclipse would generate the javadoc tremplate automatically for you.
AFAIK eclipse, visual studio, netbeans and intellij can display javadoc very conveniently, so in my opinion, it's beneficial for everyone who works with your code.
@kidburla I would write javadoc comments for protected methods because when these are overridden they will be inherited. And also if you are developing a platform application that other developers will build upon it saves the re-writing java doc comments. If the overridden methods behaviour changes and will be used by publicly then they will need to write a revised version of the javadoc comments.
|
12

Nope, you shouldn't write javadoc for private methods. End users don't have access to private fields or methods so there really isn't a point in providing javadoc for them. Private fields and methods are only meant for the developer. If you really need to though, feel free to write comments for non-obvious logic. You should probably write javadoc for protected methods because these methods are sometimes overridden and it is helpful to provide the user with some information about what the method does, or, should do.

Improve this answer

10 Comments

And what about variables?
You shouldn't javadoc private fields, but you're welcome to javadoc protected fields because they often have some significance as to why they are protected as opposed to private. You can still provide comment lines anywhere, whether it describes a variable's purpose or logic in a method.
If you provide a comment line for a private method or field, you better instead write a javadoc, this has no disadvantage, only advatages.
@AlexWien I don't disagree with your answer, but what purpose does writing javadoc for private members serve instead of comments? Members are private to prevent the user from accessing it directly (despite reflection). If you javadoc private members, aren't you making it easier for the end user to reverse engineer the program?
writing javadoc does not mean presenting it to the end user. javadoc for a private mthod gives a structuire how to (internally) comment. It demands commenting all parameters and The return value. This is a fast template, and speeds up your documenting time. To protect for reverse engineering, you have to obfuscate, and keep the public interface. Further eclipse shows a nice mouse pop over docu for a (private) method of it is javadoced
|
7

You often hear the general recommendation that, in the best case, comments should simply not be necessary at all. But concerning JavaDoc, they play an important role not only for the developer, but also for the user of the library.

Additionally, writing JavaDoc comments may be more useful for you (especially for a beginner) than for anyone else: When you find it hard to describe what a variable is or what a method does with a single /** One-line-JavaDoc comment */, then you'll automatically re-think what you have done there.

When generating JavaDocs, you may choose whether you want to generate them only for the public and protected parts of the API, or also for default- or private elements.

However, you should in any case document protected methods: May someone who extends the class only call this method, or is he also allowed to override this method? If so, are there any pre- and postconditions that he should know about? Should he call super.theMethod() in the overridden version? (BTW: If he's not allowed to override the method, then it should be final, but documented anyhow)

BTW: I personally comment everything, but know that most people think it's not necessary or even a bad style, especially for "trivial" things

/**
 * The number of elements in this set
 */
private final int numberOfElements;

I think it does not harm, but helps in many cases. Maybe, regarding private parts, it's just a matter of taste.

Improve this answer

1 Comment

"comments should simply not be necessary at all" True, but documentation isn’t comments. Comments are in-method prose that helps someone reading the source code to understand when they need to change something. Documentation is for consumers of code. This obviously applies to public and protected stuff, but also to package-private and even private stuff. Unless it’s a one-man project, documentation helps your colleagues use the methods you wrote correctly.
3

You don't have to javadoc anything, but it's very helpful to. More javadocs are never a bad thing.

Per your question, if you use the javadoc documentation compiler, javadocs will be compiled for protected methods, but not private methods. There's no reason they can't still be used as code comments, though.

Improve this answer

2 Comments

„Information is a difference that makes a difference“. JavaDoc should only be written if it expresses something the plain code/API cannot.
"More javadocs are never a bad thing" That’s not exactly true. Documentation is a form of repetition. Keeping documentation up-to-date is work and the less documentation there is, and the more important the docs that exist are, the higher is the likelihood that code changes that require doc changes are actually followed up by doc changes.

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.