Easy to Learn Java: Programming Articles, Examples and Tips

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

Home

Code Examples

Java Tools

More Java Tools!

Java Forum

All Java Tips

Books

Submit News
Search the site here...
Search...
 
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"!.

Easy Learn Java: Programming Articles, Examples and Tips - Page 397


Previous 1060 Stories (530 Pages, 2 Per Page) Next

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

Go to all tips in Story by Dr. Kabutz

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.

Heinz


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.

7028 bytes more | comments? | Printer Friendly Page  Send to a Friend | Score: 5
Posted by jalex on Saturday, September 03, 2005 (00:00:00) (2218 reads)

Getting Sun Java Certified

Go to all tips in Good To Know

Getting certified is a great way to invest in your professional development and to help boost your career potential. IT managers know the skills verified during the certification process are the same skills that can lead to increased productivity and enhanced staff credibility.

Earning a Sun Java technology certification provides a clear demonstration of your technical skills and professional dedication.

Sun offers the following certifications for Java technologies:

J2SE

  • Sun Certified Programmer for the Java 2 Platform, Standard Edition
  • Sun Certified Developer for the Java 2 Platform, Standard Edition

J2EE

  • Sun Certified Web Component Developer for the Java 2 Platform, Enterprise Edition
  • Sun Certified Business Component Developer for the Java 2 Platform, Enterprise Edition
  • Sun Certified Developer for Java Web Services
  • Sun Certified Enterprise Architect for the Java 2 Platform, Enterprise Edition

J2ME

  • Sun Certified Mobile Application Developer for the Java 2 Platform, Micro Edition

Any IT certification path can be confusing and costly. In addition to reading articles, tutorials, and newsletters on java.sun.com, you can take the Career Accelerator Packages (CAPs) to take the guesswork out of preparing for certification. Each CAP package is specific to the type of certification you want, and CAP packages are available in the following learning modes:

  • Instructor-led Training - Provides lectures and labs delivered by technical experts certified in their field as instructors.
  • Web-based Training - Entitles you to 24/7 access to courseware from a desktop or laptop and select courses include eMentoring from subject matter experts.
  • eMentoring - Provides a question and answer forum with guidance and interaction from subject matter experts and a community of learners who are taking the same course.
  • ePractice Exams - Helps you prepare to take Sun certification exams by practicing before taking the real exam.
  • Exam Vouchers - Gives you entitlement to take the certification exam at an authorized Prometric testing center.
  • Programming Assignments - Submitted online and evaluated by an expert programmer, validates your expertise as a Java programmer or architect.

Certification exams are based on recommended Sun instructor-led classes and six to twelve months of actual job role experience. Sun does not claim that by taking courses you are guaranteed to pass the certification examinations. However, the courses are an important component in certification preparation.

Once you have taken training, either instructor-led or web-based, you've had all your questions answered through eMentoring, you've taken practice exams and done well, received your voucher, and worked out an assignment, then you are ready to take the certification exam.

Exam costs vary depending on the country you live in. Sun certification exams and programming assignments are available for purchase online in four easy steps:

  1. Purchase exam or programming assignment.
  2. Schedule your exam.
  3. Take your test.
  4. Manage your certification progress.

Exams purchased on the Sun web site may only be used in the U.S. If you reside outside the U.S., check the web site to select a country to inquire about products delivered in your country.

Each exam has approximately 60 questions, and you are given 120 minutes to take the exam.

Read more:



comments? | Printer Friendly Page  Send to a Friend | Score: 4
Posted by jalex on Monday, August 29, 2005 (00:00:00) (2762 reads)

Previous 1060 Stories (530 Pages, 2 Per Page) Next

530| 529| 528| 527| 526| 525| 524| 523| 522| 521| 520| 519| 518| 517| 516| 515| 514| 513| 512| 511| 510| 509| 508| 507| 506| 505| 504| 503| 502| 501| 500| 499| 498| 497| 496| 495| 494| 493| 492| 491| 490| 489| 488| 487| 486| 485| 484| 483| 482| 481| 480| 479| 478| 477| 476| 475| 474| 473| 472| 471| 470| 469| 468| 467| 466| 465| 464| 463| 462| 461| 460| 459| 458| 457| 456| 455| 454| 453| 452| 451| 450| 449| 448| 447| 446| 445| 444| 443| 442| 441| 440| 439| 438| 437| 436| 435| 434| 433| 432| 431| 430| 429| 428| 427| 426| 425| 424| 423| 422| 421| 420| 419| 418| 417| 416| 415| 414| 413| 412| 411| 410| 409| 408| 407| 406| 405| 404| 403| 402| 401| 400| 399| 398|
397
| 396| 395| 394| 393| 392| 391| 390| 389| 388| 387| 386| 385| 384| 383| 382| 381| 380| 379| 378| 377| 376| 375| 374| 373| 372| 371| 370| 369| 368| 367| 366| 365| 364| 363| 362| 361| 360| 359| 358| 357| 356| 355| 354| 353| 352| 351| 350| 349| 348| 347| 346| 345| 344| 343| 342| 341| 340| 339| 338| 337| 336| 335| 334| 333| 332| 331| 330| 329| 328| 327| 326| 325| 324| 323| 322| 321| 320| 319| 318| 317| 316| 315| 314| 313| 312| 311| 310| 309| 308| 307| 306| 305| 304| 303| 302| 301| 300| 299| 298| 297| 296| 295| 294| 293| 292| 291| 290| 289| 288| 287| 286| 285| 284| 283| 282| 281| 280| 279| 278| 277| 276| 275| 274| 273| 272| 271| 270| 269| 268| 267| 266| 265| 264| 263| 262| 261| 260| 259| 258| 257| 256| 255| 254| 253| 252| 251| 250| 249| 248| 247| 246| 245| 244| 243| 242| 241| 240| 239| 238| 237| 236| 235| 234| 233| 232| 231| 230| 229| 228| 227| 226| 225| 224| 223| 222| 221| 220| 219| 218| 217| 216| 215| 214| 213| 212| 211| 210| 209| 208| 207| 206| 205| 204| 203| 202| 201| 200| 199| 198| 197| 196| 195| 194| 193| 192| 191| 190| 189| 188| 187| 186| 185| 184| 183| 182| 181| 180| 179| 178| 177| 176| 175| 174| 173| 172| 171| 170| 169| 168| 167| 166| 165| 164| 163| 162| 161| 160| 159| 158| 157| 156| 155| 154| 153| 152| 151| 150| 149| 148| 147| 146| 145| 144| 143| 142| 141| 140| 139| 138| 137| 136| 135| 134| 133| 132| 131| 130| 129| 128| 127| 126| 125| 124| 123| 122| 121| 120| 119| 118| 117| 116| 115| 114| 113| 112| 111| 110| 109| 108| 107| 106| 105| 104| 103| 102| 101| 100| 99| 98| 97| 96| 95| 94| 93| 92| 91| 90| 89| 88| 87| 86| 85| 84| 83| 82| 81| 80| 79| 78| 77| 76| 75| 74| 73| 72| 71| 70| 69| 68| 67| 66| 65| 64| 63| 62| 61| 60| 59| 58| 57| 56| 55| 54| 53| 52| 51| 50| 49| 48| 47| 46| 45| 44| 43| 42| 41| 40| 39| 38| 37| 36| 35| 34| 33| 32| 31| 30| 29| 28| 27| 26| 25| 24| 23| 22| 21| 20| 19| 18| 17| 16| 15| 14| 13| 12| 11| 10| 9| 8| 7| 6| 5| 4| 3| 2| 1|


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