How to Properly Comment Code? (Part I)

If you do a search in Google for "code comment" you'll find 216,000 hits and if you do the search for "comment code" you'll find 505,000 hits. Then, why is so difficult to find properly commented code?

The first point that I want to clarify is that I'm talking about "commenting code" not "documenting code" which is slightly different.

The code documentation is used to generate the API documentation, to known which methods are available, what arguments are accepted and what's the result of the call. The documentation is destined to be used and understood by the users of your code (like users of you code library and/or classes).

On the other hand, the code comments are helpful to understand the internals of your methods. Usually these comments are only read by your colleagues.

Now that the difference is clear we can continue.

As developers we usually ignore or forget the "code comments", but we always try to write some information (even minimum) when is related with the "code documentation", we even have tools to autogenerate the documentation or whine if it's not correct.

Why do we keep forgetting and ignoring the "code comments"? From my point of view there are 2 main reasons:

"It's not needed"

That's what we think when we're writing new code. At the moment the code is always so clear and beautiful that there's no need to document it. Why should we spend time? Who can be so dummy that needs extra info about our code?

Well the dummy guy that will need this comment is usually ourselves. When we come back to this block of code in the future, things will not look so clear and obvious.

"Laziness"

That's the other major reason. The typical "I'm really busy right now, I'll do it later". You known what? If you leave it for later, is almost sure that never will happen.

The lack of proper comments in our code is always going to come back in the future and bite us.

The next day we'll see some tips about how to properly comment our code.

See you.

StackOverflow and the Lazy Developers

Hi again,

During the last days I've been looking deeply into StackOverflow and I must confess that's a great source of information and knowledge. But I've also found something that worries me a bit, lazy developers.

Most of the questions in StackOverflow are really valid. Complex questions about special cases, people looking for the help of a more experience developer or even questions that can be due to a lack of knowledge in an specific subject or a part of a language or API. But I've also found a big number of questions that can only be caused by pure laziness.

Why am I saying that? Because simply putting the question keywords in google you can find the answer. I've even seen cases where the first result in Google points to the valid answer (sometimes even inside StackOverflow).

Why does it worry me? Because I've always believed that a software developer must be capable of reading documentation, creating test cases and find solutions by himself (doing trial and error if needed). If we just limit ourselves to ask the most simple questions, means that we don't care enough about what we're doing. If we just ask about stuff that can be easily in our language/API/SDK documentation, I don't want to think what we'll do with more complex problems.

This behaviors will produce tons and tons of copy&pasted code in our programs and will create a generation of developers unable to think by themselves, solve the most easy problems or understand the real consequences of the pieces of code they write.

See you soon.

Howto Install SwingX in NetBeans 6.7

Today I feel like doing some graphic stuff in my pet application. Even when Swing is really nice, I usually miss a lot of more cool effects. Just thinking in all the needed code to create an usable JTable gives me a headache.

So I've decided to use SwingX. For those of you that doesn't know about SwingX, please check their website, but as a resume I will simple say that are a collections of advanced Swing components and that some of them will become part of the default Swing set in JDK 7.

Let's start the party:

Download SwingX to you computer

You can do it from here: SwingX Download. Now I would recommend you to unpack it.

Add SwingX Library to NetBeans

1. In NetBeans go to Tools -> Library Manager and click the "New Library..." button
2. Type a name: SwingX
3. Now in the ClassPath tab you need to add the jar files you will find the /dist
4. (Optional) You can also add the SwingX sources and documentation (The SwingX 1.0 javadoc zip file is incomplete, but I used the "Hudson Continuous Build Javadoc" without problems)
   

Add SwingX to your Project

1. Right click on your project and choose "Properties"
2. Select the "Libraries" section in the left tree
3. Now click in "Add Libraries..." in the right panel
4. Select the Library you created in the previous step ("SwingX" if you followed my suggestion)
5. Finally hit the "Add Library" button

Add SwingX Components to the Palette

1. Create or open a GUI class form. You'll then see the Palette on the right side (by default)
2. Right click on the Palette and choose "Palette Manager..."
3. Click "New Category..." and choose a name. I would suggest to type SwingX again.
4. Select the newly created category and choose "Add from Library..."
5. Now choose all the components you want to have available (use Ctrl+A to select all)
6. Finally choose again the "SwingX" category
7. Click "Finish"

We're done. Now you can use the SwingX components in your NetBeans Projects.

Happy coding

The Best Way of Working with Zip Files in Java

Finally I found the best way of working with zip files in Java :)

In one of my hobby projects I need to work intensively with compressed files (mainly zip files). My first approach was to use the java.util.zip package, but was too slow. So I started looking for other options.

My second approach was to create a wrapper for the 7zip executable (so I could have cross-platform support). This approach was much better, from a performance point of view, but to retrieve any info I needed to parse console output and solve a lot of problems with the java.lang.Runtime class.

Today I've finally found the best solution .... but before some really simple comparations:

	java.util.zip	Home Made 7zip.exe Wrapper	"Best Solution"
Extract All	12203	4109	4094
Get Number of Elements	4000	4109	78

• All the measurements are in milliseconds
• The test was done with a 104MB zip file containing 110 jpg files.
• The "Get Number of Elements" with the "Home made Wrapper" is also done extracting everything and counting the number of files (I'm sorry I was a bit lazy here)

I don't think that I need to add too much to these numbers. The integrated Java zip package is nice, but painfully slow.

And finally is time to show the "Best Solution" and an example comparing it with the Java zip code ;)

The winner is "7-Zip-JBinding" and has they explain in their website:

7-Zip-JBinding is a java wrapper for 7-Zip C++ library. It allows extraction of many archive formats using a very fast native library directly from java through JNI.

Get the Number of files using java.util.zip

    static public int getSize(File file) {
   ZipFile zf = null;
   int total = -1;

   try {
       zf = new ZipFile(file);
       total = 0;
       for (Enumeration e = zf.entries(); e.hasMoreElements();) {
           e.nextElement();
           total++;
       }
       zf.close();
   } catch (ZipException ex) {
       Logger.getLogger(Zip.class.getName()).log(Level.SEVERE, null, ex);
   } catch (IOException ex) {
       Logger.getLogger(Zip.class.getName()).log(Level.SEVERE, null, ex);
   }

   return total;
}

And the same with 7-Zip-JBinding

public int getSize (File file) {
    RandomAccessFile randomAccessFile = null;
    ISevenZipInArchive inArchive = null;
    int total = -1;
    try {
        randomAccessFile = new RandomAccessFile(file.getAbsolutePath(), "r");
        inArchive = SevenZip.openInArchive(null, // autodetect archive type
                new RandomAccessFileInStream(randomAccessFile));

        total = inArchive.getNumberOfItems();

    } catch (Exception e) {
        System.err.println("Error occurs: " + e);
        System.exit(1);
    } finally {
        if (inArchive != null) {
            try {
                inArchive.close();
            } catch (SevenZipException e) {
                System.err.println("Error closing archive: " + e);
            }
        }
        if (randomAccessFile != null) {
            try {
                randomAccessFile.close();
            } catch (IOException e) {
                System.err.println("Error closing file: " + e);
            }
        }
    }

    return total;
}

As you can see the code is quite similar, but the performance is quite different.

See you.

Why do we blog? What do we learn?

Blogging takes time and only in rare occasions the bloggers make any money, so why do we do it? Jeff Atwood has a good theory. But I like to think that it is more than an "egomaniac action".

Blogging is, for sure, a good way of promoting yourself. In our blogs we put our opinions and also part of our work. A blog is a good way of showing future employers which kind of person you are.

A blog is also a way of networking, a way of sharing your knowledge, but also a way of learning from other people comments.

And the same can be said for the blog readers. I invest daily near 1 hour reading blogs and news. It is a great way of learning from other developers and stay updated.

Our profession/hobby is always evolving really fast, and blogging is, so far, the best way I have found to be in the loop.

See you soon.