JavaDoc for private / protected methods?

Question

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.

Solution 1

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;

Solution 2

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.

Solution 3

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.

Solution 4

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.

Solution 5

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.

View more solutions

Comments

[smartmouse]

And what about variables?

[Josh M]

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.

[AlexWien]

If you provide a comment line for a private method or field, you better instead write a javadoc, this has no disadvantage, only advatages.

[Josh M]

@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?

[AlexWien]

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

[cbelsole]

Does public HelloWorld() {system.out.println("Hello World")} have less value than //prints Hello World HelloWorld() {system.out.println("Hello World")}?

[AlexWien]

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.

[cbelsole]

It is a simple example to prove a point. Comments do not make code more valuable. If I can understand the code sans comments because it is written well then that is fine. Good method and variable names go a long way towards readable code.

[AlexWien]

good names, perfect written, super style, AND(!) well documented why things are done this way has more value than without that docu!

[testuser]

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.

[ashes999]

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.

[AlexWien]

@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]

@AlexWien: that's a valid point but then what's the plus in making it Javadoc comments? Why not simply keeping it as 'simple' comments? Javadoc is IMHO (a little bit, but still) more work. And for only generating the part of the public HTML, I guess it requires some extra configuration, hence, extra time spent, while you could simply add it as 'normal' comments instead.

[AlexWien]

@testuser it's far less work using javadoc: Once typing /**<Enter> the editor creates a template with all arguments of an method. And for the rest it is the same effort : writing "/**" or "//" is practically the same work. Creating the html is optional (it requires some clicks)

[testuser]

@AlexWien but you'd need to configure it that you won't generate the javadoc for non-public methods, hence it's more (trivial, not much, but still more) work to generate the javadoc then it is to write '//'.

[AlexWien]

@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.

[testuser]

@AlexWien For the record, before you start assuming things you don't know, I'm a professional Java consultant and I very well know Javadoc. You don't know the question it seems; Javadoc is "a form of" comments, what you say (very correctly) is that there certainly is a need to COMMENT your code - every part of it (including the private part). What I say: COMMENT != JAVADOC. Javadoc is a PART OF comments, but there exist a lot more ways to comment code than only Javadoc, and that's what you don't seem to know.

[Davor]

Eclipse does the same, it's a very beneficial feature.

[Davor]

@testuser - you say you are very knowledgeable, but you demonstrate some basic ignorance about javadoc.

[AlexWien]

@testuser of course there is verry need to comment ADDITIONALLY to javadoc. E.g within a method, to explain why you do something. or to comment the src of an algorithm with reference to the original author. However that what can be documented in javadoc should be. (Because this docu immedeatly pops up in the SW IDE and is helpfull for evry SW developper (and yourself) using the code.) And again its not more work to write "/**" than "//". If you have good reasons to hide information (e.g src of algorithm) then use standard comments.

[testuser]

Now your last comment is exactly what I'm trying to say. I'm not saying I know it all (in contrary to someone else here), but I'm saying you should NOT ONLY use javadoc. OP asked if he HAS TO use Javadoc. I say: you HAVE TO comment, but that doesn't HAVE TO be Javadoc. It's good practice, but I stand my point: Javadoc != Comment, comment > Javadoc only. Javadoc is a good tool and can come in handy. It's not a MUST DO though. Commenting on the other hand is. If for any reason someone comments but doesn't Javadoc things, that's still good and better than no comments at all.

[Admin]

@AlexWien totally agree, it's very nice to be able to hover over a variable (whether it's private or not) and get a quick summary of what it's supposed to be doing

[AlexWien]

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.

[ashes999]

@AlexWien that's explained in my last two paragraphs. Although Eclipse generates the docs for you, it's still a lot to write (imagine a function with 4 parameters that throws 3 types of exceptions) and maintain (as you change parameters, or the exceptions that can appear change).

[Adam Burley]

What about protected methods though (as per OP's question)? Surely you have more of a case for writing JavaDoc for those?

[ashes999]

@Kidburla I believe that code should be self-explanatory. Docs on protected methods usually fall out-of-date, and reading the code is usually more useful.

[mhbashari]

The comments for private members is useful for contributors.

[Franklin Yu]

@testuser, we all agree that some plain comment is better than no comments at all. We are just discussing whether Javadoc makes it even better, for both writing and reading.

[Pieter De Bie]

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.

[BlueWizard]

I think the example from AlexWien is really bad because he has a variable with a meaningless name and tries to inject meaning using javadoc. When you have meaningless names you basically can ignore all other good practices - it won't get better

[David]

@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.

[Edward J Beckett]

Have to respectfully disagree ~ The JDK authors do it so It's probably a good practice to follow... check out DualPivotQuickSort as an example.

[RSG]

So no maintenance in mind. Sure, if you write perfect code it may apply. With the same attitude you can delete the source after build.