Easy to Learn Java: Programming Articles, Examples and Tips

Start with Java in a few days with Java Lessons or Lectures


Code Examples

Java Tools

More Java Tools!

Java Forum

All Java Tips


Submit News
Search the site here...
Search the JavaFAQ.nu
1000 Java Tips ebook

1000 Java Tips - Click here for the high resolution copy!1000 Java Tips - Click here for the high resolution copy!

Java Screensaver, take it here

Free "1000 Java Tips" eBook is here! It is huge collection of big and small Java programming articles and tips. Please take your copy here.

Take your copy of free "Java Technology Screensaver"!.

Why I don't read your code comments ...

JavaFAQ Home » Story by Dr. Kabutz Go to all tips in Story by Dr. Kabutz

Bookmark and Share

The Java Specialists' Newsletter [Issue 039] - Why I don't read your code comments ...

Author: Dr. Heinz M. Kabutz

JDK version:

Category: Software Engineering

You can subscribe from our home page: http://www.javaspecialists.co.za (which also hosts all previous issues, available free of charge Smile

Welcome to the 39th edition of "The Java(tm) Specialists' Newsletter", sent to over 2400 Java experts in 72 countries, with the most recent addition being Costa Rica. In this newsletter I am talking rather philosophically about commenting your code, looking at some examples from the JDK. The newsletter is a bit different to my normal ones, but didn't require less work (don't all unsubscribe at once, ok Wink

Mauritius - Paradise Island. Blue sands, crystal skies, white water. *yawn* - who wants beach anyway when you could be doing computer stuff? How about adding some *real* fun to the equation? How about having your cake and eating it too? How about a Design Patterns course at the colourful Coco Beach Hotel situated at Belle-Mare on the East coast of Mauritius? To find out more about this unique opportunity to spend your tax money on a holiday Wink, click on http://vik.cshons99.net/lifetimelearning.

Why I don't read your comments

Many years ago, my brothers and I clubbed together and bought ourselves a ZX Spectrum 48k. Nice computer, especially after I stuck it inside a DK Tronics keyboard, but the problem we had with our machine was that after a random delay, it would reset itself. My big brother subscribed to a computer magazine, which included listing for games, etc. for the ZX Spectrum. There was one particular game to do with some rocket, which wasn't too long, so I decided to type it in. Somewhere in the text it said that the game had been tested only on the 16KB Spectrum, but I thought: "What the hell, I'll try it out." After *many* resets, it was finally finished, and, guess what, it never worked! One day my brother was watching me type and noticed how I was typing in all the comments (prefixed by REM). I was of tender young age and couldn't understand how the computer could understand this English comment - maybe some internal fuzzy logic, or artificial intelligence? I was most disappointed when my brother told me that REM actually did exactly zilch. Nothing. Nada. Gar nichts. Tipota. At that moment, I developed a keen distrust of comments.

After spending some years programming in Basic (without comments) I enrolled in a university degree for Computer Science. One of the things the lecturers seemed to emphasize was that your code had to have comments. Infact, due to the meanness of their spirits, they used to give us bad marks if we didn't comment our code! So, after one or two pracs with bad marks we all learned that it was a good thing to have comments. Good to have them so we wouldn't get bad marks. We then proceeded to work like this: Hack, hack, hack, hack, hack, hack. Oh, deadline time. Rename variable names from f, g, h to interest, bond, currency. Add comments before every line of code. For example (we had progressed to C at this point):

/* Conter variabble for "for" loop. */
int i;
/* Toatl of additions for calculaton */
int t;
/* Indicidual number for calclatuion */
int d;

/* "for" loop */
for (i=0; i<100; i++) { /* increment i by one until hunderd */
  d = f(); /* get ghe calue for d */
  t = t + d; /* ad it to t */
return t; /* return the variable t */

all the spelling mistakes in that code were intentional

Our lecturers, who only knew an old version of Algol, could now at least understand what we had coded, and guess what, we were rewarded for our diligence with fantastic marks. Our marks were allocated like this: Does it work correctly? 50% Was it commented? 100%

As you might imagine, through it all, I couldn't shake the feeling that I was wasting my time. Let's pan forward a few years to when I, rather naively still, started using Java. In those dark days, we didn't have fancy tools like intellisense, so I relied very much on JavaDocs. I thought JavaDocs were manna from heaven - at least we didn't have to waste our time converting our comments to documentation. Quite a few times though, I got into real trouble because I believed what was written in the JavaDocs of various libraries.

Some time after JBuilder 2, I started browsing to the source code of a class whenever I wanted to know something about it. I still use JBuilder 3, since it suits my needs very well, and whenever I need to know how to do something, I use either intellisense to remind me, or I look at the source code. It would never occur to me to read the comments that geeks like you and I had written "because it was the right thing to do". Why don't I like comments? Here are some of my reasons:

  1. I know that in most cases, they were written by programmers who didn't believe in them.
  2. There is a high probability that the comments do not adequately reflect what is really happening in the code.
  3. Code that is written well should not need comments. There are exceptions - for example - interfaces need very detailed comments to define the various conditions. Sure, if you have method names f(), g(), h(), you will need to document what the methods do, but why not call them something sensible?
  4. Instead of long pre- and post-conditions written in the comments, why not rather written extensive unit tests?

Some of these reasons are quite controversial, but I am in good company with my opinions. Let's qualify them a bit further by looking at some source snippets that made me snigger over the last few weeks.

Reminders - gotta fix this when I have time

The first one that made me laugh was found in JDK 1.3.1 in the java.awt.color.ColorSpace.getName(int) method. It had the classical computer programmer under pressure comment of "REMIND - ..."

From JDK 1.3.1: java.awt.color.ColorSpace:

   * Returns the name of the component given the component index
  public String getName (int idx) {
      /* REMIND - handle common cases here */
      return new String("Unnamed color component("+idx+")");

I went back to JDK 1.2.2 and there was exactly the same comment (didn't have source to earlier versions on my disk). I immediately opened up the source for JDK 1.4 beta, and had to chuckle even more when I looked at this:

From JDK 1.4 beta: java.awt.color.ColorSpace:

   * Returns the name of the component given the component index.
   * @param idx The component index.
   * @return The name of the component at the specified index.
  public String getName (int idx) {
      /* REMIND - handle common cases here */
      return new String("Unnamed color component("+idx+")");

Wow! So that's what idx meant! I thought it was some abbreviation of "idiots do xml". Oh, and getName() returns a name! Who would've thought that! Why didn't they rather spend more time fixing the code?

Another one that made me chuckle is java.util.Locale.toLowerCase(). Again we had a magical reminder - this time it said: "Look at optimizations later".

From JDK 1.3.1: java.util.Locale:

   * Locale needs its own, locale insenitive version of toLowerCase to
   * avoid circularity problems between Locale and String.
   * The most straightforward algorithm is used. Look at optimizations later.
  private String toLowerCase(String str) {
      char[] buf = str.toCharArray();
      for (int i = 0; i < buf.length; i++) {
          buf[i] = Character.toLowerCase( buf[i] );
      return new String( buf );

Sure this is inefficient, isn't the whole Locale class though? Even hashCode is synchronized - generally not a good idea! Why did the programmers not simply make it more optimal in the first place?

So, when do I like comments? I like comments when they provide information that I could not glean from the name of the method, such as pre/post conditions, etc. A place where comments are absolutely essential is with interfaces, since I cannot guess what the message would really do unless there was a good comment.

That's all for this week, I'm running out of time. Next week I will give you a more conventional newsletter again.


Copyright 2000-2004 Maximum Solutions, South Africa

Reprint Rights. Copyright subsists in all the material included in this email, but you may freely share the entire email with anyone you feel may be interested, and you may reprint excerpts both online and offline provided that you acknowledge the source as follows: This material from The Java(tm) Specialists' Newsletter by Maximum Solutions (South Africa). Please contact Maximum Solutions for more information.

Java and Sun are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries. Maximum Solutions is independent of Sun Microsystems, Inc.

 Printer Friendly Page  Printer Friendly Page
 Send to a Friend  Send to a Friend

.. Bookmark and Share

Search here again if you need more info!
Custom Search

Home Code Examples Java Forum All Java Tips Books Submit News, Code... Search... Offshore Software Tech Doodling

RSS feed Java FAQ RSS feed Java FAQ News     

    RSS feed Java Forums RSS feed Java Forums

All logos and trademarks in this site are property of their respective owner. The comments are property of their posters, all the rest 1999-2006 by Java FAQs Daily Tips.

Interactive software released under GNU GPL, Code Credits, Privacy Policy