Austen.Ito.Blog

I've been reading Clean Code that I listed on my list books to get through. I've read a bunch of code improvement books, but there were a couple chapters that I've gone through that I liked so far.

Writing clear functions

We've all heard that we should write functions that only do one thing. But how many of us really do it? Here is an example of how I used to write code.

public void mouseClicked(MouseEvent event) {

// Let's do something on a primary button double-click
if (event.getButton() == MouseEvent.BUTTON1 && event.getClickCount() == 2) {
// do something

}

Inline comments are evil. If they aren't updated, which can happen frequently, why not write a method that can't lie. What I should be doing is writing methods with clear names that inform developers of my intent.

Inline comments can be out of date, in the wrong place, or just plain wrong. Method names get updated automatically if you refactor your code and if the method name is wrong, the compiler let's you know.

Here is how the code should look:

public void mouseClicked(MouseEvent event) {

if (this.isPrimaryButtonDoubleClick(event)) {
// do something
}

}

public boolean isPrimaryButtonDoubleClick(MouseEvent event){

return event.getButton() == MouseEvent.BUTTON1 && event.getClickCount() == 2;

}

The code is trivial, but when your methods and classes get larger, readability and intent become increasingly more important. The longer developers have to stop and think about what your code is doing, the more it needs to be refactored. Here is what a developer might be thinking when they read my old code example:

"We want to do something when BUTTON1 is pressed and we click twice". "What is MouseEvent.BUTTON1"? *Stop to read some java docs* "So we get the click count twice. Oh thats a double-click!"

You might think that someone should immediately associate the clause to a double-click, but you might have to stop and think if you aren't familiar with the author's style or are just getting into Java. Context switching causes breaks in concentration. Not good.

In the refactored code, the developer can get to mouseClicked() and read once, "We want to do something when the user's primary button is double-clicked". No context switching, no breaks in concentration. Good.

Writing clean comments

The next thing I read that was interesting was method level comments. Here is an example of my old method level comments that I would write to pass Checkstyle and document what my method exposes:

/**
* Returns true if the primary button is double-clicked.
* @param event the event wrapping the mouse state information
* @return true if the primary button is clicked, false if not.
*/
public void isPrimaryButtonDoubleClick(MouseEvent event){

return event.getButton() == MouseEvent.BUTTON1 && event.getClickCount() == 2;

}

There are three areas of duplication. First, my initial comment duplicates what the method name states. Second, the @return tag says the same thing. Finally, the method signature clearly states what my method does and returns. Since checkstyle requires a @return tag, here is my refactored method comments:

/**
* @param event the event wrapping the mouse state information.
* @return true if the primary button is clicked, false if not.
*/
public boolean isPrimaryButtonDoubleClick(MouseEvent event){

return event.getButton() == MouseEvent.BUTTON1 && event.getClickCount() == 2;

}

I removed the initial comment to reduce the comment duplication. If the method had no parameters, the code will be reduced further:

/** @return true if the primary button is clicked, false if not. */
public boolean isPrimaryButtonDoubleClick(){

return this.event.getButton() == MouseEvent.BUTTON1 && this.event.getClickCount() == 2;

}

It passes checkstyle and reduces the amount of comment duplication. I like it.

It's Google Summer of Code time so I checked out Hackystat and tried to build it from source. A couple hours later, my Hackystat development environment was setup. Ouch.

The hardest part about setting up my environment were all of the tool dependencies. To build

hackystat-utilities, hackystat-sensorbase-uh, hackystat-sensorshell, I needed to the following libraries:

Then I needed to set the following environmental variables:

1. HACKYSTAT_UTILITIES_HOME
2. HACKYSTAT_SENSORBASE_HOME
3. JUNIT_HOME
4. FINDBUGSHOME
   
5. APACHEJCSHOME
   
6. APACHECOMMONSLOGGINGHOME
   
7. RESTLETHOME
   
8. JAVAMAILHOME
   
9. DERBYHOME
   
10. CHECKSTYLEHOME
    
11. EMMAHOME
    
12. HACKYSTATANTSENSORSHOME
    
13. ANTARGS
    
14. PMDHOME

As a developer it would be cool if I could check out the source files and run a couple of ant targets to retrieve the dependencies.

At work I've been experimenting with Ivy to download my project's dependencies. I download the dependencies to the project's library directory via an Ivy ant task and I'm done. There is no need to configure any environmental variables because the build script knows the "Home Folder" of the external libraries.

I checked on the Hackydev Mailing List and found a thread started by Aaron a long time ago called Ivy for Java hackystat dependency management.

I think it would be really useful if it were easiser for new developers to check out the source and start hacking. Integrating Ivy into Hackystat's build system might be a useful project and help to reduce Hackystat's hacking entry barrier.

I've been slacking on the blogging and the reading so to get motivated I'm posting a book queue.

1. Clean Code: A Handbook of Agile Software Craftsmanship (Robert C. Martin Series)
2. Outliers: The Story of Success (Finish reading it.)
3. Design Patterns: Elements of Reusable Object-Oriented Software (Addison-Wesley Professional Computing Series)
4. House of Leaves
5. Mentoring: The Tao of Giving and Receiving Wisdom
6. The Bro Code

My goal is to get back to reading a book a month. I've read the GoF book already, but it's time to refresh my design patterns. I read it over 3 years ago, so I will probably have a new understanding of when/where to use certain patterns.

I've also changed my reading to include fun and non-technical books. Hopefully that will keep me reading. I've noticed that it's a drag to read technical books all the time. The books are interesting, but my mind needs something new every now and then.

"Hashtags are a community-driven convention for adding additional context and metadata to your tweets. They're like tags on Flickr, only added inline to your post. You create a hashtag simply by prefixing a word with a hash symbol: #hashtag." - http://twitter.pbwiki.com/Hashtags


This past week we spent working out the kinks of our in-house testing of openmbp's basic features like posting, following, favorites, account information. We've got a bug tracker up and soon it will be filled with tons of things to work on. With the in-house test continuing for a while, I'm turning my attention to post grouping.



Twitter is going to role out groups sometime in the future and we are going to start working on getting grouping into openmbp. We are probably going to use hashtags to mark if a topic should be categorized.

Rands says that you should update your resume every 6 months regardless if you are looking for a new job or not. I haven't updated my resume in a couple of years, so this was a pretty interesting exercise. Updating your resume let's you figure out what you've done and where you are heading. So that's what I did tonight. Let's see what I learned...

What I did:

I spent a lot of time working on Hackystat. This is a good thing since I learned about Java, Ant, XML, JAXB, Postgres, and SQL.

I had one line about my work project. I'm not sure if that's a good thing, but I have learned quite a bit from my work experience.

I worked A LOT on the software development platform at work. My work experience section for my job is mostly about setting up out continious integration build server, working on our Ant build scripts, code reviews and mentoring interns. I was debating if I should put some information on trying to start a Wiki usage movement at work, but I decided against it since it didn't really pan out.

I was actually surprised that I had enough "Volunteering" items to put on my resume. I have to thank Aaron for that one.



Where I'm going:

This one was a tough one. I'm looking at my resume and it isn't clear where I'm headed. It seems that I'm interested in hacking for fun. Maybe mentor students and help developers grow or something. Looking at my resume I don't get that "ah hah" that's where he's headed.

But there's hope!

Even though OpenMBP isn't on my resume, I'm pretty sure it's the direction I'm headed. I want to build software that's useful to people. I want them to enjoy using software that I've been working on. Development on that project is starting to ramp up so I hopefully in the next resume revision I'll be able to add a new OpenMBP resume item with Ruby on Rails, Git, and an URL to the released version of our software. I think that's a good goal to have.





I really feel that I haven't done enough in the past two years. Before I started updating my resume, I was thinking that I would have lots of things to add. It turns out that I didn't really add all that much. I added some things about my work project, extra activities like Hackystat and volunteering, but it all felt a bit lacking. I couldn't add anything about the books and blogs I'm reading, the blogs I'm writing. I guess resumes are a way for companies to weed through people and find who they really want to interview. It looks like I'm going to have to work harder in the next six months to put things on my reusme that make me stand out.

Revolutionary Improvement perhaps?

Jason is an intern at the company I work for and he wrote his take on the Path to Awesomeness.  As a mentor, I hope to be helping him along his awesome journey.  I decided to write a counter-blog that talks about how I'm helping him along the way.