Simple suggestions for 'team' programming

Most programmers think that they are unique, that the way they program is the best, and they program only for themselves. This selfish attitude, however, does more bad than good. Working as a team has more advantages, less individual work, better cooperation to achieve deadlines, just to name a few, so why don't we (developers) learn how to cooperate?
Here I put four suggestions, which are so obvious to me, but I don't know why most programmers don't wish to follow:

1. Use and apply design patterns; they help better communication between the team as the provide for a common language; not to mention all the other advantages they provide, like extensible code, program to an interface etc.;
   
2. Don't hesitate to write javadoc and comments; they save another developer that looks at your methods and classes much time to know what it does than having to go through the code to realise what an uncommented method does;
3. Write test cases; they are mainly for documentation; they show another developer what is the input to a method and what to expect as an output than having to guess each time, especially when there is no javadoc;
4. Use this *bloody* CVS/SVN of yours correctly; add a comment each time you do a modification letting others know what you did and why. E.g. another guy just erased (or moved to another eclipse project) some classes in the team I work, and he never writes anything in CVS, letting me in nowhere of knowing why he did that and he 's too busy to ask.
   

If you have never heard of design patterns, then here are some references you may find useful:

• Gamma E., Helm R., Johnson R., Vlissides J. (1995), Design Patterns – Elements of reusable components, Addison-Wesley.
• Vlissides J. (1998), Pattern Hatching, Addison-Wesley.
  
• Freeman, E. & Freeman, E. (2004), Head First Design Patterns, O’ Reilly.
  
• Eckel, B. (2003), Thinking in Patterns with Java, http://mindview.net/Books/TIPatterns/
  
• JavaCamp, http://javacamp.org/designPattern/index.html
  
• Wikipedia, http://en.wikipedia.org/wiki/Design_Patterns

Write javadoc comments even to package or private methods explaining the algorithm that you use, any reference to a web site or book, and of course reference back to the use case or requirement that forced you to write this method. In eclipse it is also very easy to produce the html API by clicking on the project in package explorer and then to menu Project --> Generate Javadoc.

Creating junit test cases is also very easy with eclipse, just right click on the class you wish to test and choose New --> JUnit Test Case. Eclipse will ask you of the methods that you wish to test and will create the skeleton for you.

Next time you write a piece of code, think that you don't write it for yourself, but also for others who might review it or continue from where you left or need to modify it. Stop thinking selfishly; it doesn't help.

Heinz Kabutz also gave an interview on becoming a Better Programmer in SUN's website.

Secrets of Concurrency (Part 1) -- The Law of the Ritalin Child

Do you read Heinz Kabutz's newsletter? I do, even though I don't always understand what a Java Champion such as Heinz means. :-) As I 'm not a Java champion and I don't think I 'll ever be, I sometimes spend quite a lot of time to follow Java champions' newsletters, speeches etc. :-)
This happened with his issue 146, "Secrets of Concurrency (Part 1) -- The Law of the Ritalin Child". To understand this newsletter, on a difficult topic such as threads, I had to create some drawings on a piece of paper. So, for all the rest of you who didn't understand exactly what that issue says, or who didn't bother to look more seriously into it, here I put a drawing and my understanding of it.

So, back to our subject. The first question Heinz poses in his newsletter is what does InterruptedException mean?
Let's first examine when an InterruptedException is thrown. A thread can be in any one of the states that are shown in the following state transition diagram, i.e. NEW, RUNNABLE, BLOCKED, WAITING, TIMED_WAITING and TERMINATED. See java.lang.Thread.State if you don't believe me.

Now, assume that our thread, lets call it thisThread, is in the RUNNABLE state. Heinz says that
"[i]f the thread is not in a waiting state, then only the interrupted status is set, nothing else."
I.e., if thisThread's state is RUNNABLE, and it calls its interrupt() method, the only thing that happens is that thisThread.interrupted=true. In other words:

// thisThread is in RUNNABLE state
// when
thisThread.interrupt();

then the following occurs:

thisThread.interrupted=true;

"If the thread is currently in either the WAITING or TIMED_WAITING states, it immediately causes an InterruptedException and returns from the method that caused the waiting state."
I.e., if thisThread's state is either WAITING or TIMED_WAITING, and its interrupt() method is called, it throws an InterruptedException and returns from the method that caused the waiting state. Its interrupted status should already be true. However, as we shall see later, when an InterruptedException is thrown, the interrupted status of the thread is flipped back to false. In other words:

// thisThread is in WAITING or TIMED_WAITING state
// when
thisThread.interrupt();

then an InterruptedException is thrown and
thisThread.interrupted=false;

"However, if later on the thread calls a method that would change the state into WAITING or TIMED_WAITING, the InterruptedException is immediately caused and the method returns."
I.e. if thisThread.interrupted=true, because its interrupt() method was called previously, and thisThread called a method that causes a state transition to one of either WAITING or TIMED_WAITING states, then, because thisThread.interrupted is already true, an InterruptedException is immediately thrown and its state remains to RUNNABLE. In other words:

// thisThread is in RUNNABLE state
thisThread.interrupted=true;
// when
thisThread.wait();

then

thisThread.State=RUNNABLE
an InterruptedException is thrown and
thisThread.interrupted=false;

But how can thisThread change its state to WAITING or TIMED_WAITING? By calling one of the following methods: wait(), Thread.sleep(), BlockingQueue.get(), Semaphore.acquire() and Thread.join().

E.g.
try {
Thread.sleep(1000); // 1 second
} catch(InterruptedException ex) {
// ignore - won't happen
}

"Note that attempting to lock on a monitor with synchronized puts the thread in BLOCKED state, not in WAITING nor TIMED_WAITING. Interrupting a thread that is blocked will do nothing except set the interrupted status to true. You cannot stop a thread from being blocked by interrupting it. Calling the stop() method similarly has no effect when a thread is blocked. "
OK? Did you get that? If thisThread.State=BLOCKED, calling its interrupt() method, simply causes thisThread.interrupted=true while calling its stop() method has no effect.

The interrupted status is nowadays commonly used to indicate when a thread should be shut down because it is thrown at well defined places that wouldn't cause any problems, not like Thread.stop() method. The problem with the Thread.stop() method was that it would cause an asynchronous exception at any point of the thread's execution code.

"Note that the interrupted status is set to false when an InterruptedException is caused or when the Thread.interrupted() method is explicitly called. Thus, when we catch an InterruptedException, we need to remember that the thread is now not interrupted anymore! In order to have orderly shutdown of the thread, we should keep the thread set to "interrupted"."

So, what should we do when we call code that may cause an InterruptedException? Heinz has two answers on this:

1. Rethrow the InterruptedException from your method.
2. Catch it, set interrupted status, return

E.g.

while (!Thread.currentThread().isInterrupted()) {
   // do something
   try {
TimeUnit.SECONDS.sleep(1000);
} catch (InterruptedException e) {
Thread.currentThread().interrupt();
      break;
}
}

Remember! Don't just ignore interruptions, deal with the cause!

So, to recap:

• if a thread is in RUNNABLE state and its interrupt() method is called, its interrupted status changes to true;
• if a thread is in WAITING or TIMED_WAITING state and its interrupt() method is called, it throws an InterruptedException and its interrupted status changes back to false;
• if a thread is in RUNNABLE state and one of its methods that changes its state to WAITING or TIMED_WAITING is called, and, previously its interrupted status has been set to true by a call to its interrupt() method, then an InterruptedException is thrown, its state changes to RUNNABLE and its interrupted status changes back to false;
• finally, if a thread is in BLOCKED state and its interrupt() method is called, its interrupted status changes to true; while nothing seems to happen when its stop() method is called. (It seems that if there is a lot of contention for locks, the stop signals get lost).

Actually, for the last case, this can be checked by the following piece of code (contributed by Heinz):

public class CheckBlocking {

   public static void main(String[] args) throws InterruptedException {
 Thread t1 = new Thread() {
 public void run() {
   while (true) {
     System.out.println("t1");
     synchronized (CheckBlocking.class) {
      try {
        CheckBlocking.class.wait(10000);
      } catch (InterruptedException e) {
        interrupt();
        return;
      }
   }
  }
}
};
Thread t2 = new Thread() {
public void run() {
 while (true) {
  System.out.println("t2 blocked");
    synchronized (CheckBlocking.class) {
      System.out.println("t2");
      try {
        CheckBlocking.class.wait(950);
      } catch (InterruptedException e) {
        interrupt();
        return;
      }
    }
  }
}
};

t1.start();
Thread.sleep(2000);
t2.start();
Thread.sleep(2000);
t2.stop();
}
}

If you run this code, you will notice that no exception is thrown. It gets lost somewhere.

Thanks Heinz.

For those of you who want to learn about Java threads, I would recommend "Java concurrency in practice" by Brian Goetz, Tim Peierls, Joshua Bloch, Joseph Bowbeer, David Holmes, Doug Lea, the only book in my opinion that explains in plain english and allows you to understand what is going on in multithreading java and the strange behaviour of your multithreading programs, if you have encountered such.

java.util.Formatter

Since JDK 1.5, java has java.util.Formatter class, an interpreter for printf-style format strings. However, the API for java.util.Formatter is rather obscure to understand. This blog is to help you see each format command and its result and be able to use the most appropriate format string for your case right away, without the need to go through the long Java API for this class.

The following info applies to:

• Formatter.format()
• String.format()
• java.io.PrintStream.format()
• java.io.PrintWriter.format()
  
• printf()

but String.format() is only shown here for convenience. The same arguments can be used for the other 2 methods.

Here is a test case to display the use of format strings for date/time. I use this date as an example: 07-01-2007 22:05:01 (7th of January 2007, my name day!)

import java.text.SimpleDateFormat;
import java.util.Calendar;

import junit.framework.TestCase;

/**
* Class to test java.util.Formatter
* @author jkost
* @see java.util.Formatter
* @since JDK 1.5
*/
public class FormatterTester extends TestCase {
    private final SimpleDateFormat sf = new SimpleDateFormat("dd-MM-yyyy hh:mm:ss");
    private Calendar cal = Calendar.getInstance();

    protected void setUp() throws Exception {
 super.setUp();
cal.setTime(sf.parse("07-01-2007 22:05:01"));
}
/**
* Conversion characters for formatting dates.
*
*/
    public void testDateFormatter() {
// full day of week
assertEquals("Sunday", String.format("%tA", cal));
// abbreviated day of week
assertEquals("Sun", String.format("%ta", cal));
// full month name
assertEquals("January", String.format("%tB", cal));
// abbreviated month name
assertEquals("Jan", String.format("%tb", cal));
assertEquals("Jan", String.format("%th", cal));
// the century, 00 to 99, i.e. year divided by 100
assertEquals("20", String.format("%tC", cal));
// day of month, 2-digit format
assertEquals("07", String.format("%td", cal));
// day of month, 1-digit format, i.e. without leading zeros
assertEquals("7", String.format("%te", cal));
// Date formatted as "m/d/y" (short numeric form)
assertEquals("01/07/07", String.format("%tD", cal));
// ISO 8601  complete date formatted as "Y-m-d".
assertEquals("2007-01-07", String.format("%tF", cal));
// 3-digit day of year
assertEquals("007", String.format("%tj", cal));
// 2-digit, month of year
assertEquals("01", String.format("%tm", cal));
// no week of year; SUN needs to implement this
// assertEquals("01", String.format("%tw", cal));
// 4-digit year
assertEquals("2007", String.format("%tY", cal));
// last 2 digits of year
assertEquals("07", String.format("%ty", cal));
}

/**
* Conversion characters for formatting times.
*
*/
    public void testTimeFormatter() {
// 24-hour of day, 2-digit format, 00-23
assertEquals("22", String.format("%tH", cal));
// 12-hour of day, 2-digit format, 00-12
assertEquals("10", String.format("%tI", cal));
// 24-hour of day, 1-digit format, 0-23
assertEquals("22", String.format("%tk", cal));
// 12-hour of day, 1-digit format, 0-12
assertEquals("10", String.format("%tl", cal));
// minutes, 2-digit format, 00-59
assertEquals("05", String.format("%tM", cal));
// seconds, 2-digit format, 00-59
assertEquals("01", String.format("%tS", cal));
// milliseconds, 3-digit format, 000-999
assertEquals("000", String.format("%tL", cal));
// nanoseconds, 9-digit format, 000000000 - 999999999
assertEquals("000000000", String.format("%tN", cal));
// am or pm
assertEquals("pm", String.format("%tp", cal));
// AM or PM
assertEquals("PM", String.format("%Tp", cal));
// RFC 822  style numeric time zone offset from GMT, e.g. -0800.
assertEquals("+0100", String.format("%tz", cal));
// the abbreviation for the time zone
assertEquals("CET", String.format("%tZ", cal));
// Seconds since the beginning of the epoch starting at 1 January 1970 00:00:00 UTC,
// i.e. Long.MIN_VALUE/1000 to Long.MAX_VALUE/1000.
assertEquals("1168203901", String.format("%ts", cal));
// Milliseconds since the beginning of the epoch starting at 1 January 1970 00:00:00 UTC,
// i.e. Long.MIN_VALUE to Long.MAX_VALUE.
assertEquals("1168203901000", String.format("%tQ", cal));
// Time formatted for the 24-hour clock as "%tH:%tM"
assertEquals("22:05", String.format("%tR", cal));
// Time formatted for the 24-hour clock as "HH:MM:SS".
assertEquals("22:05:01", String.format("%tT", cal));
// Time formatted for the 12-hour clock as "hh:mm:ss AM/PM"
assertEquals("10:05:01 PM", String.format("%tr", cal));
}

/**
* Conversion characters for formatting date/time compositions.
*
*/
    public void testDateTimeFormatter() {
// Date and time formatted as e.g. "Sun Jul 20 16:17:00 EDT 1969".
assertEquals("Sun Jan 07 22:05:01 CET 2007", String.format("%tc", cal));
}

/**
* Formats the value as either "true" or "false" (or "TRUE" or "FALSE", for %B).
* For boolean values, this works as expected.
* For all other values, any non-null value is "true", while null values are "false".
* %type
* type = b | B | s | S
*
*/
public void testBooleanFormatter() {
final boolean flag = true;
// boolean
assertEquals("true", String.format("%b", flag));
// boolean
assertEquals("TRUE", String.format("%B", flag));

// as string
assertEquals("true", String.format("%s", flag));
assertEquals("TRUE", String.format("%S", flag));

assertEquals("false", String.format("%b", null));
assertEquals("true", String.format("%b", 1));
assertEquals("true", String.format("%b", 'a'));
}

/**
* Formats the value supplied as a single character.
* Supplied value must be a Byte, Short, Character, or Integer.
* %[argument][width]type
* argument = <
* width = any positive integer value
* type = c | C | s | S
*
*/
public void testCharacterFormatter() {
final char c = 'a';
// character
assertEquals("a", String.format("%c", c));
// character
assertEquals("A", String.format("%C", c));
// as string
assertEquals("a", String.format("%s", c));
assertEquals("A", String.format("%S", c));
}

/**
* %[argument][flags][width]type
* argument = < 
* flags = - | + | # |  | ( | 0 
* width = any positive integer value
* type = d | o | x | X | H | s
* Arguments must be Byte, Short, Integer, Long, or BigInteger.
*/
public void testIntegerFormatter() {
final int intNumber = 7;

// base-10 integer
assertEquals("7", String.format("%d", intNumber));

// base-8 (octal) integer
assertEquals("16", String.format("%o", 2*intNumber)); // 2*7 = 14

// flag '#' indicates that formatted output should appear in alternate form.
// For %o, this means a leading 0.
assertEquals("07", String.format("%#o", intNumber));

// base-16 (hexadecimal) integer
assertEquals("e", String.format("%x", 2*intNumber)); // 2*7 = 14
assertEquals("E", String.format("%X", 2*intNumber)); // 2*7 = 14

// flag '#' indicates that formatted output should appear in alternate form.
// For %x and %X, output will include a leading 0x (0X).
assertEquals("0x7", String.format("%#x", intNumber));
assertEquals("0X7", String.format("%#X", intNumber));

// hexadecimal representation of the value's hashcode
assertEquals("e", String.format("%h", 2*intNumber));  // 2*7 = 14
assertEquals("E", String.format("%H", 2*intNumber));  // 2*7 = 14

// as string
assertEquals("7", String.format("%s", intNumber));

// width 3
assertEquals("  7", String.format("%3d", intNumber));

// flag '-' means left justification
assertEquals("7  ", String.format("%-3d", intNumber));

// flag '+' indicates that numeric output should always include a sign (+ or -).
assertEquals("+7", String.format("%+d", intNumber));

// flag '(' indicates that negative numbers should appear in parentheses.
assertEquals("(7)", String.format("%(d", -intNumber));

// flag '0' indicates that numeric values should be padded on the left.
assertEquals("007", String.format("%03d", intNumber));

// flag ' ' (space) indicates that non-negative values should be prefixed with a space
// (for alignment with negative numbers).
assertEquals(" 7", String.format("% d", intNumber));

// flag '#' indicates that formatted output should appear in alternate form.
// For %s and %S, the flag is passed on to the object's formatTo( ) method.
// The # flag only works in conjunction with %s and %S if the argument
// implements java.util.Formattable.
assertEquals("7", String.format("%#s", intNumber));

// argument < indicates that the previous argument should be used (again),
// rather than continuing on
assertEquals("+7   7", String.format("%+d %<3d", , intNumber));
}

/**
* %[argument][flags][width][.precision]type
* argument = <
  * flags = - | + | # |  | ( | 0 | ,
  * width = any positive integer value
  * precision = any positive integer value
  * type = f | a | g | G | e | E | h | H | s
  * Arguments must be Float, Double, or BigDecimal.
  */
public void testDoubleFormatter() {
final double doubleNumber = 7.0d;

// double/float number, 6 decimal digits by default
assertEquals("7.000000", String.format("%f", doubleNumber));

// double/float number, 5 max decimal digits
// precision is the total number of significant digits to be displayed
assertEquals("7.00000", String.format("%g", doubleNumber));
assertEquals("7.00000", String.format("%G", doubleNumber));

// exponential notation, default number of decimal digits 6
assertEquals("7.000000e+00", String.format("%e", doubleNumber));
assertEquals("7.000000E+00", String.format("%E", doubleNumber));

// exponential notation, using base-16 for the decimal part,
// and base-10 for the exponent part
assertEquals("0x1.cp2", String.format("%a", doubleNumber));

// hexadecimal representation of the value's hashcode
// precision determines the maximum characters output
assertEquals("401c0000", String.format("%h", doubleNumber));
assertEquals("401C0000", String.format("%H", doubleNumber));

// as string
// precision determines the maximum characters output
assertEquals("7.0", String.format("%s", doubleNumber));

// 2 decimal digits (precision = 2)
assertEquals("7.00", String.format("%.2f", doubleNumber));

// width 6, precision = 2 (2 decimal digits)
assertEquals("  7.00", String.format("%6.2f", doubleNumber));

// flag '-' means left justification
assertEquals("7.00  ", String.format("%-6.2f", doubleNumber));

// flag '+' indicates that numeric output should always include a sign (+ or -).
assertEquals(" +7.00", String.format("%+6.2f", doubleNumber));

// flag '(' indicates that negative numbers should appear in parentheses.
assertEquals("(7.00)", String.format("%(.2f", -doubleNumber));

// flag '0' indicates that numeric values should be padded on the left.
assertEquals("007.00", String.format("%06.2f", doubleNumber));

// flag ',' indicates that the locale-specific grouping character
// should be used for numeric values.
assertEquals("7,00", String.format(new Locale("el"), "%,.2f", doubleNumber));

// flag ' ' (space) indicates that non-negative values should be prefixed with a space
// (for alignment with negative numbers).
assertEquals(" 7.00", String.format("% .2f", doubleNumber));


// argument < indicates that the previous argument should be used (again),
// rather than continuing on
assertEquals("7.00 7.0", String.format("%.2f %<3.1f", doubleNumber));
}    

public void testIntegerNumberFormatter() { 
final double intNumber = 7;

// another way to format integers
NumberFormat nf = NumberFormat.getInstance();
nf.setMinimumIntegerDigits(3);
nf.setParseIntegerOnly(true);
assertEquals("007", nf.format(intNumber));
}
}