Tag Archives: advice

Installing Eclipse

I’ve just bought myself a netbook, and following the example set by John Smart with his article on installing Eclipse, I’ll document what I do with a clean install of Eclipse.

First Things First

I download the Eclipse IDE for Java Developers. The download is less than half the size of the Java EE edition, and I can always add the extra plugins later (if needed)

Plug it in

I install the mercurial plugin. There is a pattern that I use for pushing mercurial changes to other SCMs (eg. subversion) that I will describe in another post. I intend to use Ivy for my dependency management, so I install IvyDE. I then install the code quality plugins that John mentions, as well as the Metrics plugin. (the following links are the urls for the update sites)

I also install JUnitMax. This is a new plugin from Kent Beck that runs your unit tests after every save. It’s currently on paid beta, and I highly recommend it. Subscribe here, it’s only $2/month

Templates

I update the following templates in Java -> Code Style -> Code Templates

Method Body

// ${todo} Auto-generated method stub
${body_statement}

This evaluates to an empty (apart from the comment) method for void types, or return null;. I’ve already discussed my thoughts on returning null, and I would rather my code failed if it hits an unimplemented method rather than continue in a potentially unsafe manner. So, I change this to:

throw new UnsupportedOperationException("TODO: Implement this method");

Catch block body

// ${todo} Auto-generated catch block
${exception_var}.printStackTrace();

I’ve also discussed my thoughts on checked exceptions. I prefer to not silently hide the exception with a stack trace, I also don’t want to make my callers deal with checked exceptions, so I change this template to:

throw new RuntimeException("TODO: Handle this exception better", ${exception_var});

Test Templates

I also create a new test template in Java -> Editor -> Templates. I copy the Test method (JUnit 4) and add some Behaviour Driven Design style guiding comments. Because I’m lazy, I name it T :-)

@${testType:newType(org.junit.Test)}
public void should${DoSomething}() throws Exception {
  // Given 
  ${cursor}
  // When
  // Then
}

Favourite Imports

I add the following classes to Java -> Editor -> Content Assist -> Favorites so that I can get type completion on my favourite static imports

  • org.hamcrest.CoreMatchers.*
  • org.hamcrest.Matchers.*
  • org.junit.Assert.*
  • org.mockito.Mockito.*

Code formatting

These are the changes I make to the default Eclipse settings for my personal code.
In Java -> Code Style -> Formatter

Indentation -> General Settings -> Tab Policy => Spaces only 
Indentation -> General Settings -> Indentation size => 2
Indentation -> Indent -> Statements within 'switch' body => on
Control Statements -> General -> Insert new line before 'else' in an 'if' statement => on
Control Statements -> General -> Insert new line before 'catch' in a 'try' statement => on
Control Statements -> General -> Insert new line before 'finally' in a 'try' statement => on
Control Statements -> 'if else' -> Keep 'return' or 'throw' clause on one line => on
Line wrapping -> Line width and indentation levels -> Maximum line width => 132

I also make the following changes to the compiler warning settings (Java -> Compiler -> Errors / Warnings)

Potential Programming Problems -> Serializable class without serialVersionUID => Ignore
Unnecessary Code -> Unused Import => Error

What should my code tell me?

When I’m reading code, there are a number of things that make my job much easier.
The most important (in my opinion) is good naming, but how can we choose suitable names?
This is the pattern that I am starting to see (and recommend), and I think it is pretty effective.

What? How? Who? Why?

If we think of the code as a medium of communication, what questions should the code be able to answer?

What are we trying to achieve?
The method name should be a summary of what we are trying to achieve. For example, public void selectTheCustomerNamed(String customerName) {...}
It is (hopefully) clear from the method name what will happen when we call it, and what we need to pass in in order for the code to work.

How do we do this?
The body of the method should be the steps needed to achieve what it is we said we would do in the method name. The steps should be at the same level of abstraction. (See Composed Method)

public void selectTheCustomerNamed(String customerName) {
theUser.clicksOn(Application.SEARCH_BUTTON);
theUser.types(customerName,into(SearchPage.CUSTOMER_NAME));
theUser.clicks(SearchPage.BEGIN_SEARCH);
theUser.clicks(ResultsPage.FIRST_RESULT);
}

Who is doing the work?
In the example above, by naming the receiver of the messages after the actor who is likely to perform these steps, it helps focus the mind, and can help with appropriate method naming. For example, we can ask ourselves “What does theUser need to do next?”

Why are we doing this?
At one time or another, you will probably come across a comment like this:

// Add one to foo
foo++;

This kind of comment is irrelevant at best, it is telling us what the next line is doing. If the methods are well named, or the code is idiomatic, this is unnecessary. One negative consequence may be a kind of “comment blindness” where your mind filters the majority of comments as “noise”.
A better use of comments is to explain why we are doing things in a certain way, especially if it seems unusual. Martin Fowler briefly mentions this in the “Code Smells” chapter in Refactoring.
An example of this type of comment is shown below. This represents a hard-won piece of knowledge, and will hopefully prevent a well-meaning programmer from replacing the code with the getFooByQuery variant without checking the caching behaviour.

// We query the id first before trying to retrieve the object, because if we try to
// retrieve the object directly (with getFooByQuery), it always bypasses
// the cache (see @link{...})
Integer fooId = findFooIdByQuery(query);
return getFooById(fooId);

JavaDoc can also be used to tell your users why they might need to pay special attention. If the code is well named, you are unlikely to need JavaDoc for all classes.
Here are some examples of where you might like to use JavaDoc:

  • If you have a number of pluggable modules, why would you want to use this module
  • Reasons why a user might want to provide their own implementation of this class
  • Reasons why this code throws exceptions, and why a user might want to handle them

This is still a work in progress, but the results that I have seen so far have been encouraging. Please let me know in the comments if you have any suggestions for refinements or improvements.

Well, how did I get here?


And you may find yourself living in a shotgun shack
And you may find yourself in another part of the world
And you may find yourself behind the wheel of a large automobile
And you may find yourself in a beautiful house, with a beautiful wife
And you may ask yourself, “Well… how did I get here?”

Once in a Lifetime – Talking Heads

Logging a Stack Trace in log4j

A while ago, I was trying to replace a number of hard coded strings with an appropriate Enum. Unfortunately, the design of the code I was working on meant that it was difficult to find all the possible values for the strings.
I decided that the behaviour that I wanted was:

  • If the string method was called with a new value, log that value, so that I can make a decision about whether I wish to add it to the Enum
  • If the string method was called with a value that matched a value in the Enum, I wanted a stack trace, so I could replace that call with the appropriate Enum call

The code I ended up with was something like this:

public void doSomething(String theDestination) {
if(weKnowAbout(theDestination)) {
logger.debug("doSomething called with a known destination of " + theDestination, new Throwable());
}
else {
logger.debug("doSomething called with unknown destination of " + theDestination);
}
doWhatWeNeedToDoWith(theDestination);
}

Passing the new Throwable() into log4j creates a stack trace in the log output. I’ve found a number of places that tell you how to do this (now that I know how to do it), but it took me quite a bit of searching when I was first looking.

Returning ‘null’ Considered Dishonest

Background

Antony Marcano and I have just started running a coding design workshop. Most of the audience are new to coding and we are trying to focus on good habits that are applicable across all programming languages.
In our first session, we created a vending machine. By the end of 90 minutes, it was able to dispense a drink as long as it had sufficient money and stock available.
One of the questions that we asked was “What do we do when the customer has not inserted enough money and we press the button for the drink?”
Some of the people who had some programming background said “Return null”, which is what brings us to this post.

Good Citizen

In the wiki for the PicoContainer project, there is a page titled “Good Citizen“, which details a number of good practices that all Java classes would benefit from trying to adhere to.
The practices make a lot of sense when you think about them, but they aren’t really explained. I’m going to try and address that issue as we cover them in the workshop.
The practice that we are looking at today is “Never expect or return null”, with a dash of “Fail Fast” for flavour.

What’s so bad about null?

In the Java world, when we declare a method signature, we specify a return type. In the case of our vending machine we had:

public Drink giveMeADrink() {...}

By declaring that the return type is Drink, we are signing up to return something that “is-a” drink.
We could also return null, which is a nothing value. We could use this to represent that you did not get a drink.
The client code may look something like this:

myVendingMachine.giveMeADrink().downInOne();

If we return null, this code will fail with a NullPointerException. Not particularly useful, but at least we are using the result straight away. The problems become much worse if we store the returned Drink for use later.
When we said we will always return a Drink, we lied.

Programming Defensively

The sample client code above makes the assumption that the result of giveMeADrink will be a Drink. Given that we’ve actually signed up to that contract, that doesn’t seem to be unreasonable. But now the client code is broken and they have an angry customer, they are going to have to work around the issue. It would probably look like this:

Drink myDrink = myVendingMachine.giveMeADrink();
if(myDrink != null) {
myDrink.downInOne();
}

This code is actually saying “I’ve asked you to give me a drink, but I don’t trust you, so I will check first”.

Why isn’t this working? An Exceptional Approach

If we rely on our client to check that they received a valid result, we lose out on an opportunity to let the client know why the call was unsuccessful.
In the Programming Defensively example, we can recover from being returned a null, but we don’t know why it was null. Was it because we hadn’t inserted the money? Was it because the machine was out of stock? Was it because the stars were out of alignment?
Do we handle the scenarios differently? If we haven’t inserted enough money, that’s something we can deal with, but if the machine is empty, we need to look for another machine.

What if our code looked like this?

public Drink giveMeADrink() {
if(weDontHaveEnoughMoney()) {throw new NotEnoughMoneyException();}
if(weDontHaveEnoughStock()) {throw new DrinkOutOfStockException();}
return new Drink();
}

What we have said is “We will always give you a drink or tell you why we couldn’t

Now when we attempt to call giveMeADrink, it lets us know straight away if it can’t proceed. It also gives us a good indication of why it is having problems.
The client code calls:

myVendingMachine.giveMeADrink().downInOne();

and gets told “Sorry, I’d give you a drink, but you didn’t insert enough money“.
Our code is being honest, polite and giving the client an opportunity to remedy the situation. The customer is still angry, but now he’s angry with himself for not putting in enough money.

In Summary

  • Programming defensively is programming distrustfully
  • Returning null is dishonest. It requires others to check that we’ve upheld our side of the bargain
  • Throwing a meaningful exception allows us to let the caller know why their call did not succeed

Singletons

I’ve been playing about with a code base that has a large number of singletons, for what appears to be no apparent reason.
Something about singletons doesn’t sit quite right with me, but in the most part, if they’re not misbehaving, I’ll probably leave them be.

The thing that bothers me a lot more though, is the fact that everyone else is forced to know about your singleton-ness..

ImASingleton.getInstance().doSomething();

*shivers*

If you have to store global state, it would be nice if we could hide that from the clients. Why do we have a single instance with instance variables accessed through a static getInstance method, when we could hide (ooh, encapsulation) the implementation behind multiple instances with private static variables?
By using instance methods, we also get all the interface / testing / mocking goodness.

new ImASingletonButYouCantTell().doSomething();

OK, I’m rambling… am I missing something? (please rant below)

Static Utility Methods

A few of us were chatting about static methods the other day.
I’m not a big fan. I think that they tie you unnecessarily to a concrete class.

Most people were saying that there is no harm in having static methods in utility classes, and this is one place where I would disagree.
The example used was the java.lang.Math class with it’s utility methods.

java.lang.Math is non-instantiable, you can only access it’s utility methods through static calls.
For the most part, this is fine, but take the example of Math.sqrt(x)
This method returns NaN if x is < 0. For the majority of cases this is fine, but if I start working with complex numbers, then this is no longer the ideal behaviour.
Admittedly, in this case I would not want the return value to be a double, but I may want it to throw a ComplexNumberException or something similar. If I have used the static method throughout my code, I now have to go and update every single reference to the concrete class. What a pain in the class!

However, if I had used a utility class with instance methods, I could have injected the utility class in the constructor and I could now change it out for my new ComplexMathUtility class through configuration / DI.

This isn’t the best example, as the required return types are different, but think of a String utility class, perhaps something that formats a header for a report.
We could (naively) implement this using static utility methods. If we later require two different types of report heading, this is going to make our life difficult.
If we implement this using an instantiable ReportFormatter, we can swap in new ones at runtime / configuration. We’ve just implemented a ReportFormatterStrategy :-)

My feeling is that implementing utilities as instance methods keeps the design flexible and allows for more code reuse as things naturally gravitate towards smaller, more easily testable, logically grouped units of functionality…
Or am I just dreaming? :-)

Refactoring / Design: Composed Method

I’m going to try and write a few posts over the next few weeks around the subject of Refactoring and Design. This is mainly practice for me, so that when asked to explain, I don’t confuse the issue. All comments and suggestions are gratefully accepted.


When I am looking at code, I feel a lot more comfortable if a method is composed of several steps of similar context, in the appropriate order.

This is the Composed Method pattern from Smalltalk Best Practice Patterns.
In Refactoring To Patterns, Joshua Kerievsky says that this is one of the most important refactorings that he knows, and I would have to agree.

Here is an example that I just thought of (see if you can guess what I was doing):
public class CheeseCake {

private final Person chef; private final Sink kitchen; private CakeTin<CheeseCake> cake;

public CheeseCake (Person chef, Sink sink) {
this.chef = chef;
this.sink = sink;
}

public makeBase(Ingredients... ingredients) {
sink.runUnderWater(chef.getHands());
sink.useSoap(chef.getHands());
sink.dry(chef.getHands());
Bowl<Ingredients> bowl = new Bowl<Ingredients>();
for (Ingredients i : ingredients) {
bowl.add(i);
}
bowl.mix();
CakeTin<CheeseCake> cake = new CakeTin<CheeseCake>();
cake.add(bowl.contents());
}

}
Wow, we have quite a few smells in this code, and not the pleasant smells of cheesecake cooking either…
We’ll ignore the Feature Envy and things for the moment, but I’ve only just written this code and already I’m having trouble telling what it does at a glance…

What about if the makeBase method looked like this:


public makeBase(Ingredients... ingredients) {
washHands();
Bowl<Ingredients> bowl = addTo(new Bowl<Ingredients>(), ingredients);
bowl.mix();
cake.add(bowl.contents(); // Moved CakeTin creation into constructor
}

That looks much better, but not only that, we also find that the washHands() method is used extensively. Now each step in the recipe doesn’t need to implement their own hands washing routine.

It’s also much more obvious that washHands has absolutely nothing to do with CheeseCake, and much more to do with either Person or Sink… maybe we’ll look at this next time :-)