Saturday, December 19, 2009

An easyb jUnit runner

I intended my next post to be about Mercurial, and I will get to it, but I had something else to write about. As I mentioned before, we are using easyb for our unit testing framework. It’s pretty nice, and I like it so far. It has an Eclipse plugin, but it just outputs to the console. Also, we are using Hudson for our CI server, and there isn’t really any Hudson integration for easyb either. Not having good integration was starting to bother me, so I decided to do something about it.

I don’t have an endless amount of time to spend on it, so I figured the path of least resistance was to create a jUnit runner that would run the easyb behaviors. That way the output would integrate into Eclipse and Hudson automatically.

It was a little tricky to get it to work properly because easyb tests are written in Groovy, and you can’t easily determine the makeup of a story or specification without actually running it. But I have something that works pretty well, and gives nice feedback, with good integration with Eclipse and Hudson.

I created a project on Google Code to host it, so you can check it out here: http://code.google.com/p/easyb-junit

I describe how to use it on the project site. I hope this is useful to other people. If you have any issues with it, or ideas to make it better, please let me know.

Monday, December 14, 2009

Technologies we are using

My current project has given my team a great opportunity to use some newer web technologies. Prior to starting this project there were several things I had been looking at for a while and was interested in using. So, I’m going to list all the technologies we are using in this post and say a little about them. Then I’ll follow that up with a post about each one, and some details on what we are doing with them and things I’ve learned. These are in the order that we decided on using them.

Mercurial

In previous jobs I’ve use PVCS, ClearCase, CVS, and Subversion. I don’t really have anything to say about PVCS, except that I was glad when we quit using it. ClearCase was too heavy handed, and a pain to deal with. CVS works well, but has some major performance issues and is missing a lot of nice features of more modern VCS systems. Subversion does fix some of the issues with CVS, but every project I’ve worked on with Subversion, everyone ran into major issues when trying to merge code. Add to that some other oddities we ran into with Subversion, and I wasn’t very happy with it either.

I’d read a decent amount about the new distributed version control systems like Git and Mercurial. Although I never really understood why people liked them so much. I didn’t really get it until I read the first chapter of the Mercurial guide about distributed version control. I ended up deciding to go with Mercurial. The main reason I went with it over Git was the Eclipse plugin for Mercurial seemed a lot better. Git seems to be too tied to the command line. Not that I hate the command line, some times I use it with Mercurial, but I like good IDE integration with a VCS.

Gradle

I used Maven 2 back when it hadn’t been out very long. It was really cool how quickly you could get a build up and running with it. However, my team at the time had a bad experience with it. It cost me a few days of work a couple times, fixing weird build errors caused by plugins that got automatically updated. All those things that Maven just does for you can be a real headache when they aren’t working right. In the end, the issues we kept having with Maven lead us to switch to Ant and Ivy.

So, for the last four years or so I’ve been using Ant for builds and Ivy for dependency management. Ant is great because you can literally do anything with it, and I really like the way Ivy does dependency management. But it can take a lot of work just to get a build working. And all the XML can be a pain. GANT is a nice solution to the XML, but it still takes a lot of effort to get the build running.

A while ago I came across a new build tool called Gradle. It uses Groovy for writing the build instead of XML, so adding a bit of logic to your build is simple and straightforward. It also uses some of the build by convention concepts that Maven has, so getting a simple build running is a snap. It also has tight integration with Ant, so calling ant tasks is simple. It uses Ivy under the covers for dependency management, too. All in all, it looked like a nice option, so we decided to try it out.

GWT

I’ve kept track of GWT since it first came out. I’ve played around with it a few times, but never really got a chance to build anything with it. I really like the idea behind GWT. It’s not that I dislike JavaScript, I like it just fine, and jQuery is fun to work with. But I can’t really imagine building the entire front end of a rich internet application using JavaScript. It’s just too hard to test and debug, in my opinion. And I don’t really want to develop for Flash or Silverlight. So that leaves GWT. Which, to me is a great option.

Grails

I’ve done a couple small projects with Grails, and been pretty impressed. You can really get things done quickly with it. It takes some getting used to, and doing TDD feels different than Java. But once you get the hang of it, it’s a nice environment to develop in. We looked at a couple different options for the backend of our system, but decided Grails would be the best choice.

SOFEA

With the back end and front end in place, there was still a decision to make about how they would communicate with each other. A friend of mine told me I should read about SOFEA. It stands for Service-Oriented Front-End Architecture. The concept is that the front end is completely client side and controls the flow of the application. The back end is simply a bunch of stateless services that the front end calls.

Matt Raible is really big on this right now. He’s been using this architecture with GWT as the front end and Grails as the back end. We liked the idea of a clean separation between the front and back end that SOFEA presented, and had already decided to go with GWT and Grails. So it seemed natural to go with SOFEA also.

Easyb

The last thing we decided to use was Easyb. We were definitely going to be doing TDD, but we liked the concepts that the BDD style had. Although you can do BDD in jUnit, it doesn’t really feel all that natural of a thing to do, and it’s really easy to fall back into some bad testing habits. I was hoping there was a better solution out there.

I looked at JDave, but felt like it looked too verbose. I had heard of Easyb before, but never really looked at it. Once I checked it out I found that I really liked it. It uses Groovy instead of Java. Which adds some flexibility, and since we are using Groovy with Grails, it wasn’t another language to learn.

I found writing Easyb specifications is pretty similar to how I was doing TDD in jUnit, just nicer. I still use Mockito for mocking, and my tests are structured very similar to how they were before. They are just easier to read, and you aren’t tempted to fall back into the non BDD tests like you can be with jUnit. Also, Easyb has a nice HTML report that it outputs as part of our build. It’s a great tool! Well worth a look, if you haven’t seen it before.

Well, that’s it. That’s a lot of new stuff, but I think it’s already coming together pretty nicely. As I said at the beginning, I will be blogging about each of these technologies in the coming weeks. Until next time…

Sunday, December 6, 2009

One line of code

One is the magic number. At least it is for two things when it comes to writing code.

The value of really small methods

The first thing one is the magic number for is the number of lines of code in a method. I first heard this from Brian Button in a TDD class he gave a couple years ago. He was talking with someone else and asked them what they thought the optimal number of lines of code in a method was. I think the other person answered something like 10 or 15. “Nope,” Brian said, “it’s one!”

One line of code per method! That sounds crazy! It sounded pretty far fetched to me at that time, too. But Brian is a smart guy, so I thought I would give him the benefit of the doubt and really try it out. That was a couple of years ago, and I’d have to say that I’m definitely a believer now!

Now, like pretty much everything in programming this is not a hard and fast rule. You have to consider context and use judgment like with everything else. So, I’m not saying every single method should have only one line. That wouldn’t work. I just mean it’s an ideal to shoot for. The closer you get to it, the better off you’ll be.

I’ve worked with people in the past who said they believed in “self documenting code.” What they really meant by that is: “I don’t write comments.” They didn’t actually write self documenting code, they just didn’t document the confusing code they wrote. If a class is 500 lines long and made up of a bunch of 20 to 80 line methods, it’s not self documenting. Just because you don’t comment it and say it’s self documenting doesn’t make it so. Creating self documenting code takes intentionality, thought, and effort.

One of the biggest things you can do to make your code self documenting is to break it down into small methods. Methods whose size approach one line of code. If you do this, you will understand your code better. The next person that has to read it will understand it faster. And with good method names, you will have real self documenting code.

As I’ve worked at coding this way over the last few years, I’ve noticed a few things. One is that when I have to go back to a class that I wrote with really small methods, I rarely have to spend much time at all remembering how it works. I find that I can understand how it works much faster than I could when I wrote classes with big methods.

I’ve also noticed my definition of a big class or a big method has really changed. I used to work on a system that had classes that where thousands of lines long with methods frequently being hundreds of lines long. Now when a class gets to 100 lines, I start really feeling like I need to break it up. And I am rarely willing to put more than about 5 lines in a method. Quite a change.

Another thing that I’ve noticed is that shooting for one line methods helps reveal a lot of code duplication. The other day I was writing a class, and I had all the tests written and the functionality complete. Now it was time to refactor. So I started breaking the logic down into smaller methods. As I did this I noticed that two of the methods actually had a lot more in common than I realized. I was pulling several of the same small methods out of each. Then I realized that if I implemented another method they both used a little differently, I could collapse both methods into just one line of code. This change lead to a 10% reduction in the size of the class due to code duplication. Duplication that I wouldn’t have even noticed, if I hadn’t been creating all those little methods.

So, writing one line methods may sound extreme, and it is just an ideal, not a rule. But if you adopt it, I think you’ll find your code is easier to understand, easier to modify, and contains less duplication. That’s a nice combination.

But wait, there’s more

There’s another thing for which one is the magic number. I read a blog post a while back that I wish I could find, but I search around and couldn’t find it. In the post the guy was saying that if you are creating a new class, API, or feature you should not consider it done until it can be used/called with one line of code! This is something I wish people would think about more.

When you are writing something, think about the code that will have to be written to call your code. Is there too much setup for even simple uses? Can it be called with one line of code? Again, this isn’t a hard and fast rule, but it’s something you should shoot for. Especially for simple things that people may want to do with your code.

For instance, say you have a file and you want to read the lines of the file into a list of strings. Now, that’s a pretty simple thing and should only require one line of code. Well, this is how it would look using java.io:

I suppose that’s not too bad. It’s only about 6 lines, but that’s a lot more than one. This is a simple and common operation, there’s no reason it should take more than one line of code. Of course, if you have Apache IO Utils on the class path, it is only one line:

That’s the way it should be. I don’t really understand what the designers of this API where thinking on this one. I guess they got so caught up in making a flexible API that can do anything, that they forgot to make it easy to use for simple things. They forgot to make sure it could be used with one line of code.

And don’t even get me started on JDBC! Oh man, what a pain!! Look, if I want to query the database with a couple parameters and get a string out, that’s pretty basic, that should only require one line of code. If it takes more than one line of code with your database framework, then get a new one. I don’t even want to think about how many lines of code it would take to do it with raw JDBC.

So, the moral here is, when you’re writing a class or an API, think about the calling code. Refactor and add helper methods if you have to, but strive to make your code as easy to use as possible for clients. Don’t make them write the same 3 or 5 lines of code every time they want to do something basic and common with your code. Aim for one line of code.

After all, one is the magic number!

Thursday, December 3, 2009

Using an ivy.xml with Gradle

I’ve been using Gradle on my current project. So far I really like it. It follows the ‘build by convention’ idea that Maven uses and is even easier to extend and add to than Ant. One of the main reasons is the build file is actually just a Groovy file. So adding logic is simple.

One of the problems with any new tool, though, is wide spread support. Usually the IDE department is the biggest issue here. Gradle uses Ivy for dependency management, but it does it under the covers. You specify your dependencies in the build.gradle file using the Groovy syntax. It’s actually nicer than XML. The issue is getting your IDE to recognize the dependencies declared in your build file. There aren’t any plug-ins for this yet. This is no good as far as I’m concerned, because it makes adding jars to your project way too hard.

Today I decided I needed to add Mockito to my project, and ran into this issue of trying to figure out how to have it in my Gradle build file and on my Eclipse classpath. It annoyed me enough that I considered just dropping Gradle and going with Maven. Then I realized that since the build file is just Groovy, it should be pretty simple to have an ivy.xml file and just read it in the build file and insert the dependencies programmatically. It turns out this was pretty simple. Here’s how it worked.

In Gradle you specify your dependencies by declaring a dependency section in the build file like this:

You can also represent a dependency as a list of strings like this:

It’s important to note that all that is happening here is you are passing a list of strings to a method called ‘compile’ and ‘testCompile’. So, I realized all I have to do is write a function to build these strings off of the ivy.xml file.

Using the XML processing power of Groovy this is actually really easy. I changed the dependency section to look like this;

This code just parses the ivy.xml file and looks for dependencies that match the conf you specified (or have no conf at all) and adds them to the list of dependencies. It ignores some of the advanced features of Ivy, but it works for what I needed it to. Now I can just use IvyDE in Eclipse and have the same dependencies in my IDE as Gradle uses when it builds.

Saturday, November 28, 2009

Customizing an Eclipse distribution

When I do Java development I usually use Eclipse. When you’re working with a team, I’ve found it’s really helpful to make sure everyone is using the same version of Eclipse with the same plug-ins and settings. In order to do this you can just package up a few more things with the Eclipse distribution. Since I’ve done it several times now I thought I would document what you have to do. I thought others might find this useful, also.

Setting up the workspace

The first thing I like to do is to build a workspace that goes with Eclipse so I can setup all the settings in the workspace. Doing this for things like code formatting and templates ensures everyone’s code will look as similar as possible. There’s also a lot of other settings you may want to setup so no one else on your team will have to.
To do this just download the distribution of Eclipse you want to start with and unzip it (for this example I’m using Eclipse IDE for Java EE Developers version 3.5.1). Then start Eclipse. Since this is the first time you will be opening Eclipse it will prompt you for where you want your workspace to be. Just clear out want it in the box by default and type ‘workspace’ and check the box at the bottom that says ‘Use this as the default and do not ask again’. It should look like this:
create-workspace
Click OK. Eclipse will then create a folder called ‘workspace’ under your Eclipse folder. From now on when you open this Eclipse it will automatically use this folder as the workspace. Now you can install all the plug-ins you want and setup all the settings you want and they will be carried with this distribution.

Packaging the JDK

Another thing you may want to do is package a JDK up with the distribution so you know for sure that everyone is using the same one. Also, this means that Eclipse will run even if the person does not have any version of Java installed on their machine (this does introduce a platform dependency, though).
The easiest way to do this is to find a JRE you have already installed on your machine and just copy it into a folder called ‘jre’ under the Eclipse folder. When you run the eclipse.exe file it looks for a ‘jre’ folder in the Eclipse folder, if one is found, then it will launch using that JRE. However, this is often not preferable because some Eclipse plug-ins (like the Maven 2 plug-in) require you to be running Eclipse on a JDK not just a JRE. So it’s best to use a full JDK. You could just take a JDK and copy it into a folder named ‘jre’ under the Eclipse folder, but that could be misleading, and there’s another way.
Take a JDK you have on your machine and copy it to a folder called ‘jdk’ under your Eclipse folder. Also in that folder there is an eclipse.ini file that is used for setting certain parameters to the exe and the Java VM. Open that file and put these two lines at the top:
-vm
jdk/bin
This will tell Eclipse to use the VM you put in the ‘jdk’ folder.
Now you can just zip up the Eclipse folder and give it to your team.

Bonus: Bundling Gradle with the distribution

For my current project we are planning to use Gradle for our builds. I wanted to be able to bundle it with the Eclipse distribution and setup an external tool configuration so it would be easy to use for anyone else.
To do this I downloaded the latest version of Gradle and put it in a folder called ‘gradle’ under the Eclipse folder. Then, in Eclipse, I created an external tool configuration like this:
external-tool
This will work fine as long as the person that uses it has their JAVA_HOME set to a valid JRE. But we’d rather have this work without that variable set. The gradle.bat file specifically looks for the JAVA_HOME variable to be set and will error out if it’s not. You can set this value to something using the Environment tab in Eclipse, but I couldn’t find any way to get this to work in a way that would function properly on everyone’s machine. So I ended up just modifying the gradle.bat file and adding a line that sets the JAVA_HOME variable to the ‘jdk’ folder under the Eclipse folder. The modified file looks like this (the added line is in bold):
...
set DIRNAME=%~dp0
if "%DIRNAME%" == "" set DIRNAME=.\
set JAVA_HOME=%DIRNAME:~0,-12%\jdk
...
It’s a bit of a hack, but it works. If anyone has any better ideas, I’m surely open to it.

Thursday, November 19, 2009

Passion for your craft

I've been thinking about starting a blog about technology and business for while, but never actually took the time. I decided now was a good time to do it. However, for my first post, I'm really just going to direct you over to the Software by Rob blog. If you don't read it already, you should consider it. He had an excellent post today about Passion as a Competitive Advantage. I thought it was great and truly believe in the importance of being passionate about what you do.

In the article Rob says:
Passion translates into being insulted when people don’t care about things as much as you do and are willing to hack a crappy solution together. It’s an insult to you, your product and your craft.
One thing that passionate people love is other passionate people. When you really care about what you do, you want to work with people who also care about what they do. The last thing you want is to have to work with someone who is just trying to put in their forty hours a week. And, as Rob puts it:
If you don’t have passion for your code/product/startup everyone will know. It’s obvious you aren’t that into it, and people will not take you seriously. Without passion it’s impossible to convince people to believe in your vision.
I started out in college in Chemical Engineering. I made it through my third year and was only 30 hours away from graduating. Toward the end of my third year I was sitting in a principles of chemical engineering class, and the professor was chewing us out for not putting much effort into our latests assignment. We were doing a design and analysis of a distillation column, and a lot of us (myself included) didn't do a thorough job and just turned in a half baked solution. Not surprisingly the professor, who was passionate about his field, was practically insulted by our lack of effort.

Then the professor said something that changed my path in school. Actually, he asked a question. He asked, "Why would you turn in something poorly done, if you care about what you're working on? And if you don't care, why are you getting this degree?" I sat there and thought, "That's a good question! Why am I getting this degree?" The was effectively the end of my career as a Chemical Engineer.

The summer before that I had taken a C++ class that was required to complete my ChemE degree. I really loved it. I did more than the class required, and would often just program things for fun. In one of my ChemE classes we had to write a program to solve a problem. The professor actually supplied a mostly complete program in some strange math environment and said we just had to complete it, if we wanted to do it that way. Everyone else did that, but I wrote my own from scratch in C++. I thought it would be more fun that way. Incidentally, mine was the only one that worked correctly.

So, when that professor asked us why we were getting a degree in ChemE if we didn't care about it, I decided that Computer Science made more sense. This was something I did really care about, and something I loved doing. And the rest, as they say, is history.

I graduated in 2001 with my CompSci degree and still love programming. It's been great getting paid to do something I love to do. And I've enjoyed all the time I've spent reading, practicing, and learning more about software development. 

After eight years I believe even more in the importance of passion for what you do. I love working with passionate people, and I'm always baffled by people who don't seem to care. They should have had a professor like I did and had to face the question, "if you don't care, why are you getting this degree?" If you aren't doing something you are passionate about, then do yourself and everyone else a favor and go find something you are passionate about. You'll be glad you did.