• Post Reply Bookmark Topic Watch Topic
  • New Topic

Do you create JavaDocs for package private classes and public classes of internal use?  RSS feed

 
Avor Nadal
Ranch Hand
Posts: 156
Java Netbeans IDE Postgres Database
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hello:

For the last weeks I've been trying to get me into the habit of putting JavaDocs to my public classes and methods. I don't use them in private classes and methods though, because I write my code so that it's as much self-documented as possible (with the exception of some sporadic comments here and there).

However, I've doubts about whether to put JavaDocs in package private classes and public classes that are not going to be used by the consumer of the API. Those of you who don't put JavaDocs in private methods, What do you do in these cases? Do you treat them just as regular public classes?

Thank you.
 
Campbell Ritchie
Marshal
Posts: 56534
172
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
That is the ideal, to create documentation comments for everything. But it is hard work.

Think: If you come back to a class you wrote in Spring 2014, can you remember how to use it? If you are not sure, then you needed documentation comments. If you can remember most of it or nearly all of it (rather than all of it) then you needed documentation comments.
 
Avor Nadal
Ranch Hand
Posts: 156
Java Netbeans IDE Postgres Database
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
OK, I got it. Out of curiosity, Do you write JavaDocs for private methods too?

I tried to write JavaDocs for everything some weeks ago, but I found it difficult to document it while I was building all the logic. It distracted me a lot. In the end I programmed some classes and methods and, some days later, I took time to elaborate the JavaDocs. Is it an acceptable approach, as long as I remember how they worked?

I also had to use the folding feature of my IDE to collapse the comments, to avoid distractions (changing the colour to a dim one helped too). Any advice about it?
 
Junilu Lacar
Sheriff
Posts: 11477
180
Android Debian Eclipse IDE IntelliJ IDE Java Linux Mac Spring Ubuntu
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Just the fact that you are making an effort to write JavaDocs at all should be applauded.

I personally don't write many JavaDocs for private methods since, as you said you do, I also try to make my code as self-documenting as possible to eliminate the need for comments. JavaDocs for public methods, I do more often than not. I have not written many package.html JavaDocs, maybe 3 or 4 over the years, and I've been programming in Java for almost 15 years now.
 
Junilu Lacar
Sheriff
Posts: 11477
180
Android Debian Eclipse IDE IntelliJ IDE Java Linux Mac Spring Ubuntu
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
For package private classes, I'll usually make a developer note to explain why the class is package private. This, hopefully, heads off any misguided attempt to increase the scope of the class by anyone who wasn't involved in making the decision and privy to the conversation that transpired when the decision was made. Here's another post I made regarding my approach to commenting: http://www.coderanch.com/t/642114/java/java/Newbie-java-code-assignment#2949002
 
Avor Nadal
Ranch Hand
Posts: 156
Java Netbeans IDE Postgres Database
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Junilu Lacar wrote:Just the fact that you are making an effort to write JavaDocs at all should be applauded.


Thank you, he he he. One of the main reasons why it costs me to write JavaDocs is because English isn't my mother tongue and I've to take my time to think what I want to write (as when I do in these forums :P ) . I could write them in my first language, because right now I'm the only one who edit this code. But I prefer to do it in English because:

1. It's universal.
2. Programming is inherently in English, so I prefer to be homogeneous.
3. I don't want to lose my little skills with the English language.

Junilu Lacar wrote:For package private classes, I'll usually make a developer note to explain why the class is package private. This, hopefully, heads off any misguided attempt to increase the scope of the class by anyone who wasn't involved in making the decision and privy to the conversation that transpired when the decision was made.


Very good idea. I'll apply this to my code, because sometimes I feel tempted to widen the scope of a package-private class.

What I'll do.

I've been comparing the quantity of public/protected methods in my code against the number of private methods. And the former are many more. This means that I'm going to need very often to write JavaDocs. The high quantity of public methods is, in part, because I like moving those private methods that may be re-used by other classes into auxiliary classes. And it requires to convert such private methods in public ones.

Although I'm an advocate of self-documenting code, I've to admit that I always end with extremely long field and argument names which become hard to read. So I've taken the decision to try again to make JavaDocs for private methods too. They'll document my methods better and, at the same time, will allow me to use less complex names.

I also have decided to use more frequently the feature Navigator in NetBeans IDE and Outline in Eclipse IDE to not get lost among the dense JavaDocs.

Thank you both for your advices!
 
  • Post Reply Bookmark Topic Watch Topic
  • New Topic
Boost this thread!