Do you document your private methods and fields?

I do.

I realized this not long ago when I was trying to use a field, forgot exactly
what its type was, put my cursor on top of it and waited for the tooltip to

Now, why would you want to add JavaDoc comments to parts of your code that
will be skipped by JavaDoc?  For your IDE, of course.

In theory, you should never need this since the class and the name of your
fields should be self explanatory, but there are times when real comments come
in very handy.  Compare:

List<Account> m_accounts;


Map<String, List<Method>> m_groups;

Again, this example is a bit borderline.  When your types become a bit
contrived such as the one shown above, you should probably consider creating a
class to hold them:

public class GroupMap extends Map<String, List<Method>> {

or even better, use composition instead of inheritance to make sure you only
expose in your API what you really need.  Still, this practice is sometimes
overkill, especially when this private field will only be used in one class.

Exposing privates is something that is very Java-y.  I remember being
quite surprised the first times I read Java code.  Not only were
implementations and interfaces mixed up in one class, the private fields were
shown at the top of the class!  C++ programmers usually put the private
parts of their classes at the very bottom of their code in order to focus on the
important (public) part of their class, and you tend to browse header files more
than the real implementation when you are trying to find out how to use an API.

It took me a while but I finally got used to it.  I still think there are pros and cons
to this practice, though:

+ When you read a class, seeing the private fields first might give you a
better sense of how the class works.

Very often, the first thing I’m interested in when I read the code
of a class is its constructors, and private fields get in the way of this

Still.  At the end of the day, if you see some Java code that is not
immediately obvious to you, the simple fact that you’re wondering whether you
should add a comment or not means you probably should.

How about you, do you document private methods and fields?