1 0
post icon

How To Make A Useful Error Message Your Users And Support Team Can Understand

Your application is finally being deployed, and run­ning now in the real world. It is your application and the user now, face-to-face.

The user will inter­act with the appli­ca­tion, be that too often or oth­er­wise, doesn’t mat­ter, but inter­ac­tion is at least there.

Since the user is inter­act­ing with your appli­ca­tion, makes us assume that it at least met the user’s require­ments who will be expect­ing some sort of reac­tion each time a request is made.

But, the ques­tion that arises here is: What if the appli­ca­tion failed in react­ing to the user’s request? Or, what should be done if some sort of fail­ure occurred?

A good solu­tion is to show an error mes­sage, since we don’t want the user to stay there con­fused and just won­der­ing what has just happened.

Another ques­tion arises: How should the error mes­sage look like?

Let’s not for­get that when­ever an issue occurs with the appli­ca­tion, the user will look for sup­port, and you, or if a com­pany, the sup­port team, will be the target.

So, imag­ine that the error mes­sage that you have designed to be dis­played when­ever a fail­ure occurs was some­thing like the one shown in the fol­low­ing figure.

When the user gets the error, he will most likely make a call and tell you or the sup­port team that he had an error, and the error was: Sorry, seems some­thing went wrong!

What will you do? How will you deal with such error? And, how will you diag­nose it?

Yes, a gen­eral error mes­sage doesn’t help.

A good prac­tice to do as a devel­oper here, is that when you test your pro­gram, pre­tend as if you were the user of that pro­gram. (I want to men­tion here that I will not go deep in dis­cussing the roles of the devel­oper and the roles of the tester, and the dif­fer­ences between the two, I’m just try­ing to empha­size how to feel with the user)

So, when test­ing a new func­tion­al­ity in your appli­ca­tion, pre­tend as if you were the user of the appli­ca­tion. Hav­ing an error occur, look at the error mes­sage, and ask your­self the fol­low­ing two questions:

1– Is it easy for me to under­stand the error message?

2– Does the error mes­sage help me locate the problem?

If you answer “Yes” to the above two ques­tions, the error mes­sage is most likely use­ful, and thus, will be easy for the user to under­stand, and for the sup­port team to locate the prob­lem. Oth­er­wise, the con­trary is true.

Did you notice something?

Yes, the first ques­tion is tar­geted to the user, and the sec­ond one is for the sup­port team.

The issue here is pro­vid­ing some sort of bal­ance and rec­on­cil­i­a­tion for an error mes­sage that com­bines between two dif­fer­ent tar­gets, the user, and the sup­port team.

A workaround for this could be in doing two things:

1– Dis­play­ing an easy to under­stand mes­sage that tar­gets the user.

Exam­ple: Could not login

2– Hyper­link­ing the text in the mes­sage to tar­get the devel­op­ers and testers. In this case, users, devel­op­ers, and testers, can fol­low the link and pro­vide more infor­ma­tion on the error (The link in this arti­cle is just an http:// link for descrip­tion pur­poses)

Exam­ple: Could not login [Click for more details]

The issue here is pro­vid­ing some sort of bal­ance and rec­on­cil­i­a­tion for an error mes­sage that com­bines between two dif­fer­ent tar­gets, the user, and the sup­port team.

We can also add the func­tion­al­ity of send­ing the error mes­sage through email to the sup­port depart­ment once click­ing on the link. And, this is suit­able in stand-alone systems.

There are other tech­niques in han­dling and report­ing errors, such as log­ging, but as you saw in this arti­cle, we want some­thing that bal­ances between the user and the sup­port team (Devel­op­ers and testers).

In this case, we will not leave the user clue­less, and, at the same time, we will be able to increase the func­tion­al­ity of the sup­port team espe­cially when it is easy to locate the error.

Abder-Rahman Ali

Ref­er­ence

Prac­tices of an Agile Developer

Read full story »
31. Mar, 2010
post icon

New To Java? Know The Code Structure

Some­times, when we begin learn­ing a new pro­gram­ming lan­guage, we start by dig­ging deep into the code and are in a hurry to come up with some­thing tan­gi­ble, some­thing that works and makes us feel happy.

We go into code imme­di­ately think­ing that this will be the short­est path to learn that new pro­gram­ming lan­guage. But, sud­denly, we find the time pass­ing and pass­ing and we are not in the pace that we expected.

At the end of the day, we dis­cover that we are stuck, time has passed, and we are not at what we should be.

Will the rea­son be always a com­plex issue?

Well, I think one of the rea­sons to that may be so sim­ple, such as, we are not aware of how the code struc­ture fits.

So, for those newly com­ing to the Java pro­gram­ming lan­guage, I rec­om­mend them know the struc­ture of the Java code, which will enable them to write code in a struc­tured manner.

And, below, you can find a fig­ure that shows how the Java code is struc­tured out.

Click on the image for a larger view

Abder-Rahman Ali

Ref­er­ence

Head First Java, 2nd Edition

Read full story »
28. Mar, 2010
post icon

Let’s Count. Java, Java2, Java5, Java6… Am I Missing Something Here?!

When we are count­ing nat­ural num­bers (The ordi­nary num­bers we use), we go like this: 1, 2, 3, 4, 5, 6, 7, …etc

This is the nor­mal process. But, let us go back to the post title once again, and see how we were count­ing the Java ver­sions. We began with Java (Denotes 1), went to Java2 (2), after that Java5 (5). Is there some­thing miss­ing here? In other words, where is 3 and 4?

Let us fig­ure what hap­pened with Java those days.

The first offi­cial release of Java was ver­sion 1.02. From this ver­sion till ver­sion 1.1, all those ver­sions were Java.

Java didn’t remain at 1.1. A new ver­sion, namely, 1.2, was devel­oped. OK, why not bun­dle this ver­sion as the pre­vi­ous ones within Java? Well, the issue was that ver­sion 1.2 had dra­matic changes, and you know, if the name remained as Java, it may not be clear for many peo­ple that there are dra­matic changes out there, in other words, mar­ket­ing had a role.

So, the search was for a new name. This new name was Java2. So, ver­sion 1.2 was con­sid­ered Java2.

It was then until ver­sion 1.5 were the changes were dra­matic. Thus, time for a new nam­ing convention.

Will that new name be Java3?

If we go back to how the name of ver­sion 1.2 came up, we can con­clude the fol­low­ing two points:

1. There was a dra­matic change.

2. Java2 was the name of ver­sion 1.2

Let us now apply those two points on ver­sion 1.5 by walk­ing through the fol­low­ing flowchart:

What did you come up with from the pre­vi­ous flowchart?

Do you think that Java3 would be a suit­able name con­ven­tion to ver­sion 1.5?

We can see that it may make some con­fu­sion here, such that, there is no con­nec­tion between 3 and 1.5. So, Java3 would not be a good nam­ing convention.

What would be a good nam­ing con­ven­tion then?

Based on how ver­sion 1.2 was named, we can say that Java5Tiger” (The orig­i­nal code-name) would be a good nam­ing convention.

So, there was never a Java3 or a Java4, and you did not miss anything.

The fol­low­ing table sum­ma­rizes what ver­sions were included in which nam­ing con­ven­tion until Java5.

Version(s)Nam­ing Convention
1.02 — 1.1Java
1.2, 1.3, and 1.4Java2
1.5Java5
Abder-Rahman Ali

 

Ref­er­ence

Head First Java, 2nd Edition

Read full story »
27. Mar, 2010
post icon

How To Make Your Java Code Understandable

You may be work­ing on the devel­op­ment of a sys­tem at your com­pany. You have been work­ing in cod­ing some mod­ule. And, it has been around 6-months since you last worked on that module.

Today, your man­ager has asked you to make some mod­i­fi­ca­tions to that module.

You said to your­self: “Well, that is no prob­lem at all, I have coded most of that mod­ule, and really very aware of how it oper­ates”.

You fired up your favorite edi­tor. Your fin­gers began tin­gling. And, you are ready to the coding.

You headed directly to the required class to start your oper­a­tion.

Yes, this is my code. Look who’s the author (@author)”, you said confidently.

So, let the oper­a­tion begin.

What is the prob­lem?! Why are you star­ing like that?!

And it stopped there.

Have you ever gone through such scenario?

So, as you can see, this may hap­pen to us with our own code. But, why is that?

Yes, you may be doc­u­ment­ing the code, or hav­ing com­ments for spe­cific parts of the code, but, at the end of the day, you may be won­der­ing why you even did that, what was the rea­son, and many many other ques­tions that may come to your mind.

If you fall in such cir­cum­stance, we can say in brief that the code is  NOT under­stand­able.

What good in a code if you or oth­ers can­not under­stand how it works and what it is about.

The case is really sen­si­tive here. Yes, we have to make our code under­stand­able even with­out commenting.

One way to do that is to make the code clear and obvi­ous to see what is happening.

I think it is now time for an exam­ple to make what we talked about so far more clear.

Assume that you have the fol­low­ing line of code:

 coffeeShop.placeOrder(1);

Is this code under­stand­able? Well, we can under­stand that we are plac­ing an order in a cof­fee shop. But, the ques­tion here is: What are we actu­ally order­ing? 1?!

What good in a code if you or oth­ers can­not under­stand how it works and what it is about.

So, it is not clear from the code what we are try­ing to place.

A way to solve this issue is by adding a com­ment as follows:

 coffeeShop.placeOrder(1); // 1 is small cup size

But, we don’t want com­ments to com­pen­sate for this poor code. We want the code to be under­stand­able in its own.

A workaround for this would be in defin­ing an enum as follows:

enum CoffeeSize {SMALL, MEDIUM, LARGE }

In this case, the plac­ing order code could look as follows:

 coffeeShop.placeOrder(CoffeeSize.SMALL); 

Look at the code once again. Isn’t it more descrip­tive? And, thus, under­stand­able?

So, what we learned here is what’s so called the PIE (Program Intently and Expres­sively) prin­ci­ple, and it states the following:

Code you write must clearly com­mu­ni­cate your intent and must be expres­sive. By doing so, your code will be read­able and under­stand­able. Since your code is not con­fus­ing, you will also avoid some poten­tial errors. Pro­gram Intently and Expres­sively.

Abder-Rahman Ali

Ref­er­ences

Prac­tices of an Agile Developer

SCJP, Sun Cer­ti­fied Pro­gram­mer for Java 6 Study Guide

Read full story »
25. Mar, 2010
post icon

Thoughts For Students From The Father Of Java

James Gosling, best known as the father of the Java pro­gram­ming lan­guage, gives in the below video some thoughts for stu­dents relat­ing to Java.

Abder-Rahman Ali

Read full story »
24. Mar, 2010