March 13, 2006

Privacy exposed

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

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;

with

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

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?

 

Posted by cedric at March 13, 2006 04:32 PM
Comments

Sometimes. In most of the work I do, the main reason for the Javadoc in the first place is to use it within the IDE - in this context, documenting privates make sense.

However, since I started using Java 1.5, most of my private comments have faded - mostly, I used them to document the contents of collections.

Posted by: Robert at March 13, 2006 08:18 PM

I think its ironic to talk about what the IDE can do for you when you use the eye-sore (and completely redundant) techniques of IInterface and m_field.

TestNG is nice, but the source makes my eyes water ;)

Posted by: ct at March 13, 2006 09:17 PM

I'm almost surprised you didn't document your privates, since javadocing all the code is the only way you can be sure your code can be read by another developper without issues.
But, well, sometimes, they're not documented that good ;-)

Posted by: Nicolas Delsaux at March 14, 2006 01:04 AM

Usually I have complete Javadocs for all public methods and fields, and describe them in all details (allowed argument range, exceptions etc). For private members I only use simple comments, only one line most of the time. It makes less sense to have a complete documentation for private methods, as a) those who see them also have the full source code, and b) they tend to change more often than public methods.

Posted by: Tim Jansen at March 14, 2006 01:09 AM

There's nothing more annoying than this:


/** Mobile phone number */
private String mobilePhoneNumber;


except may be this:


/** A string field used to store the mobile phone number of this customer */
private String mobilePhoneNumber;


or this:


/** Temporary storage for the difference between m_optiplex_frida and pqrKK_H. This field is initiali....
.....
Added on May the 24th by Jason to comply with spec HGJ17, might remove it later...
*/
private String g_x_hamster;

Posted by: George Petrov at March 14, 2006 02:07 AM

> "javadocing all the code is the only way you can be sure your code can be read by another developper without issues"

How about putting the info in the field name? With the refactoring support in modern IDEs, it is easy enough to change a field name (esp. a private one). So if you can't immediately tell what the field does, give it a better name.

Btw, I totally agree with ct that using naming conventions like m_field is pretty useless, esp. when your post is about adding metadata for IDE use. Your IDE can tell you what type the field is, can't it?

Posted by: Tarik Idris at March 14, 2006 02:49 AM

That is the matter of how obvious it is. If you can easily guess what this method/member does based on its name and signature, then the comments are not required.

Posted by: at March 14, 2006 09:16 AM

In the case of this one, the means of effecting it, by murdering most of the English political Úlite, was so sensational and so morally disturbing to most people, that the chances of somebody blowing the whistle on it were unusually high.

That is exactly what happened; one of the people brought into the plot in its later stages (probably the unstable Francis Tresham) told an opportunist peer, Lord Monteagle, who tipped off the government. The other reason why the plot was a guaranteed failure was simply that the powder would not have blown.

When it was moved to the Tower of London magazine after Guy Fawkes was caught, it was discovered to be `decayed'; that is, it had done what gunpowder always did when left to sit for too long, and separated into its component chemical parts, rendering it harmless. If Guy had plunged in the torch with Parliament all ready above him, all that would have happened would have been a damp splutter.

'...the plot was a guaranteed failure was simply that the powder would not have blown.'

Both these fatal weaknesses were contingent, however, on one accident of history; the postponement of Parliament. It had originally been scheduled to meet on 3 October 1605, and only the lingering traces of bubonic plague in London made it seem sensible to put off the occasion for a month.

Posted by: Professor Ronald Hutton at March 14, 2006 10:02 AM

In the case of this one, the means of effecting it, by murdering most of the English political Úlite, was so sensational and so morally disturbing to most people, that the chances of somebody blowing the whistle on it were unusually high.

That is exactly what happened; one of the people brought into the plot in its later stages (probably the unstable Francis Tresham) told an opportunist peer, Lord Monteagle, who tipped off the government. The other reason why the plot was a guaranteed failure was simply that the powder would not have blown.

When it was moved to the Tower of London magazine after Guy Fawkes was caught, it was discovered to be `decayed'; that is, it had done what gunpowder always did when left to sit for too long, and separated into its component chemical parts, rendering it harmless. If Guy had plunged in the torch with Parliament all ready above him, all that would have happened would have been a damp splutter.

'...the plot was a guaranteed failure was simply that the powder would not have blown.'

Both these fatal weaknesses were contingent, however, on one accident of history; the postponement of Parliament. It had originally been scheduled to meet on 3 October 1605, and only the lingering traces of bubonic plague in London made it seem sensible to put off the occasion for a month.

Posted by: Professor Ronald Hutton at March 14, 2006 10:03 AM

I used to worry over order of things. It made a lot of sense when I used to print out source code and read it. Later, I would read it in the text editor--not an IDE, just an editor.

That made sense back then.

Now, I just make 4 groups in my source file.

1) At the top are the class/static and instance variables and any initializers, which are all static. I sometimes put static variables before the instance variables but its not really a rule I use.

2) Constructors go next. If there is a no-args constructor I always put it first.

3) Methods go next. I don't worry about the order except I like get and set methods to go at the bottom where I don't have to look at them.

4) Inner classes go at the very bottom. Sometimes this gets messed up when I automatically add some get or set methods for new attributes and they go at the bottom.

Finally, since I use Eclipse, I set the outline view to order things in this order and I click the button to sort by name within the groups. (The only time I switch back to the unordered view is the rare case that I want to reorder the methods by dragging them in the outline view.

Its funny how I used to obsess (sp?) over the order of methods and now I spend no time at all on it. The time saved by the tool makes it work.

Posted by: Lee Meador at March 16, 2006 11:23 AM
Post a comment






Remember personal info?