Javadoc/Comments in Code

A work colleague "Richard Paul" suggested some very good ideas about what things should be included in javadocs/comments when coding. So I thought I should write about it to spread the knowledge.

Comment design decisions and why you did it that way

There was a situation at work were we wanted to know why a particular variable was used in a calculation over another variable. Then we started to think back to why we did it that way and this had happened a while ago so not a lot was recalled. We needed to know this because we needed to change the variable being used and couldn't recall if there was any special reason why we used that variable.

But if we had documented in the javadoc why we used that variable over another variable that would have made things much simpler.

Most of the time developers document how their code works in the javadoc. This is good when the code is complex and hard to understand. In the ideal world the code should be well written that very little javadoc is required to explain what is happening. But we believe it is also important to document why you have done something in a particular way. Also any coding design decision should be commented.

I will give you an example to better explain what I mean.

I had to implement an interface for a listener to perform a particular task. Now the event for this listener had 3 different event types.

One option would be used to implement the interface directly and use if statements to handle the 3 different event types.

Another option would be to add an abstract class in the middle which would handle the if statement and delegate to 3 abstract methods. So instead of implementing the interface, you extend this abstract class and instead of implementing 1 method, you now have 3 abstract methods to implement.
The reason I did this was because the code was more clear as to what each method was doing. Also if in the future we wanted another implementation, we could extend the abstract class and the common logic is still in the abstract class and it would be easy to substitute classes.

So, some of the reason I outlined above should be added to the javadoc of the abstract class. So that when someone looks at the code in the future, they will understand why I used an abstract class instead of implementing the interface directly.

Company's might have procedures in place to write supporting document about the code. But this might be hard to locate and might take time. But having some of the reasons in the code makes the information available quickly.


Comment your unit tests

Another place that comments become very useful is in unit tests. Testing code is very important and I might write another post explaining why later on.

So what do I mean?
Each test case you write should be testing a particular case. So sometimes its a good idea in the javadoc of the method to summarise the input and output of the test case. Now if you are creating all the input data inside the test case, then this javadoc might not seem very useful. But if you have created your input data in the setup method of the testing class, then its not very obvious what are the inputs. Creating the input data in the setup method reduced redundancy and is the logical thing to do to make your tests maintainable.

I will give an example to explain what I mean.

public class TestPerson extends TestCase {

protected void setUp() throws Exception {
Person person1 = new Person("name1", 10); // name and age of person
Person person2 = new Person("name2", 11);
// etc
}

/**
* The people should be allocated by name
* Data:
* Person1 - Jane
* Person2 - Bob
* Person3 - Steve
* Outcome: a list in the order Bob, Jane, Steve
*/
public void testAllocatePeopleByName() {

}
}

This is just a simple example demonstrating the concept of commenting your tests.

Now if that Test Class was very long, that javadoc becomes very useful. Instead of scrolling to the top of the test to see the details of the input data in the setup method, you have a summary in the javadoc of the test method.
Maintaining the code and tests now become much easier. If you wanted to maintain this code in the future or if someone else looks at it, they would be able to understand and comprehend it much faster saving time thus money.

Greasemonkey

So what is Greasemonkey?
Greasemonkey is an addon for Firefox that allows the user to write scripts which alter the web page dynamically.

Userscripts
This site contains scripts which can be used by Greasemonkey. This would be a good place to have a look to get an idea of what things can be achieved. Its a place where user share their scripts with everyone.

If you know some web technologies like HTML, CSC and javascript, you will be able to write your own scripts.

More information about this can be found on wikipedia

Fixing issues after new windows xp installation

After I installed Windows XP, there was nothing in the Network Connections so I could not connect to the Internet using my router. Also sound was not working and some games were not working.

How to fix this
You need to install the drivers for the motherboard.
You first need to find out the model of the motherboard.

• You could open up the computer and check the model number written on the motherboard.
• Check the specification of your computer. Maybe the invoice for the computer contains a list of components.
  

For example my motherboard was an "Intel D915". So you just go the google and search for "Intel D915 drivers".

So on the Intel website, there were 4 drivers

1. A driver so that the basic components on the motherboard work correctly
2. A sound driver
3. A network driver (This created a LAN network connection)
4. An advanced graphics driver. I believe for the on-board graphics card

So after installing all those drivers, everything is working fine.

Rock Climbing for Beginners

If you have never been rock climbing before, then your first experience is quite interesting. So I thought I shall share some interesting things that I learnt. This is indoor rock climbing. Not that actual thing.

I am only going to go over the basic things a learnt. If you want more details then there is always wikipedia.

Since it was my first time, the people working there give gave me and work colleagues a demo about safety and how things work. Also wearing a harness for the first time can be difficult and can be uncomfortable at first.

The demo started of showing how to climb a wall with a belayer. I think it was a top rope system. So the climber attaches themselves to one end of the rope. This rope goes to the top of the wall and then comes down to the belayer who is also attached to the rope. The belayer stands about 5 metres away from the wall.

So as the climber climbs the wall, the belayer has the pull the rope so the rope between the two is always tight. So that if the climber falls, they only fall a small distance. They have special systems attached onto the rope, so that if you do fall, the rope automatically locks, so its quite safe. Then once you have reached the top or have had enough, you can let go of the wall and the belayer will slowly bring you down.

How they measure difficulty
The rock climbing walls have colour coded holds(placed where you put your hands or feet). Each of the colour coded holds are given a level which is shown on the wall. And the aim is to use a single colour to get to the top. If you can then you have achieved that level. Simple as that.
Easier levels have many holds which are large and easy to grip. Harder levels have fewer holds in hard to reach locations and are difficult to grip.

Lead climbing
Another style of climbing that I saw was lead climbing. There is still a belayer, but as the climber climbs its there responsibility to clip themselves into clips along the way. This style is for more experienced rock climbers.

Don't need a belayer
There where also tall narrow walls which don't require a belayer. There is still a rope that you have to clip your harness on, but as you climb the wall there is a mechanism that keeps the rope tight and if you fall, it automatically takes you down slowly.

Bouldering
Instead of going up the wall, in bouldering you go across. In other words rock climbing sideways.

So that was my first experience regarding rock climbing and I recommend that you try it once.

Dual boot Windows XP and ubuntu 8.10

I bought a second hand computer for real cheap so I thought it might be a good idea to try and setup a dual boot using windows xp and ubuntu 8.10

I asked a few people at work and they said it would be very straight forward so I decided I should give it a go and I had nothing to lose. But the journey was harder than I thought.

It is a good idea to install windows xp first. This is because if you decide to install windows second, windows overrides the boot load so you wont get the option of which operating system you would like to load up.

Before you start installing anything, you should decide how the hard drive should be partitioned to accommodate the dual boot. Now I had a 120GB hard drive. So I wanted 40GB for windows, 40GB for ubuntu and 40GB as a separate partition for my files so that both operating systems can access it.

By default, ubuntu can view and modify the contents in the windows partition but windows is unable to even see the ubuntu partition.

Installing windows xp first

So the mission began and installing windows was easy but it takes a while. Maybe about 25 to 30 minutes. So when I was asked about the partitions at the start I only created one 40GB partition and left the rest as free space. The rest of the installation is straight forward.

Let me say, windows xp is extremely fast on the clean installation. The time from computer startup to desktop is like 15 seconds. There is hardly any loading time for the operating system.

But I had a major problem. I had nothing in the "Network Connections" so I could not connect to the internet. The computer was connected to the router but I could not connect to the LAN. I believe some network adapter drivers are missing. But this is a separate issue I will discuss later.

Next installing ubuntu 8.10

The live feature available when installing ubuntu is very handy. It loads up quickly and you can use the operating system without having to install it. It detected being connected to my router automatically and I could browse the internet straight away. So its good how everything just works without having to do anything.

Then on the desktop there is a icon called "Install" which allows you to install ubuntu through a nice wizard. Everything is straight for apart from the Partition section.

There are a few options when decided where ubuntu will be installed.

1. The first option is resizing an existing partition to make room for ubuntu. The problem was that it was only resizing the 40GB I had allocated for windows.
2. There are 2 other options but both of them result is using the entire disk (120GB) for ubuntu.
3. The last option was to setup the partition manually, but this requires some advanced knowledge regarding allocation of disk space required for ubuntu. Like allocation space for the root, swap etc

None of these is what I wanted. I already had 40GB for windows and I wanted to use the free space I had left.

After some researching, I found out there is a "Partition Manager" option in the "System" menu on the live running system. This allows you to manage the partitions on the disk.
You can add, edit and delete partitions.
So after some fiddling around, I created a FAT32 partition at the end of the disk and resized the windows partition to take up 80GB. Resizing partitions is quite simple because it involves dragging a rectangle to the size required.

Then I started the installation progress again and when I got to the partition section I selected the first option of resizing the windows partition which I changed to 80GB. So know is have 40GB for each operating system. The rest of the installation is straight forward.

Finally

Now its was time to restart the computer and to see which options I would be confronted. These are the options:

1. Load ubuntu, the name started with ubuntu but there was lots of random text afterwards.
   
2. This had the same text as the first but the "(Safe)" at the end
3. There is an option to load another operating system.
4. The last option is windows xp