Articles Feed

Lending a Hand

by: jim | August 21st, 2007 | 0 comments »

At Agile 2007, we put on a workshop called RailsFest. The original intent was to provide a one-day session that conference attendees could visit to get an opportunity to work on a Ruby on Rails project. What that project was to be, we didn’t really know. In the way that things sometimes work out, we ended up with the opportunity to work all week with a non-profit organization that has touched more lives than most of us ever will.

The organization that we were working with is called Mano a Mano. Their mission is to “improve the health and well-being of impoverished Bolivians.” Segundo Velasquez, president of Mano a Mano, was our on-site customer, and I was lucky enough to work with him for part of the week. At first, he was a little unsure of his role in the process, but by the end of the first afternoon he had become comfortable in expressing what he wanted the software to be. It was a lot of fun watching Segundo learn about and adapt to the approach that we were taking in creating software for his organization.

Mano a Mano works in a very different way than most other charity organizations. Though they provide aid to the economic poor in Bolivia, it is not a free handout. The intent of the whole process is to bootstrap poor communities. Segundo told me of a specific project where they were able to increase the per capita income by 100% (from $150 to $300) the first year. By helping to provide the basic necessities that we often take for granted (e.g. potable water, roads to allow for the transportation of goods and people, etc.), the citizens were able to stop worrying about these basic things and concentrate on improving the lives of themselves, their families and their community.

Though RailsFest ended last Friday, there is still work to be done. If you are interested in giving back a little bit through your craft, please drop me a line at jim (at) 8thlight (dot) com.

RubyCocoa Tutorial

by: eric | August 13th, 2007 | 22 comments »

Admit it, you’re new to Rails. You just got your new spiffy Rails job, and they gave you a Mac, formerly the computer of long-haired starving-artist types. It’s got pretty apps with and even a Remote Control, and it’s got you thinking about making desktop applications. Then you remember the Resource Files, C++, Windoze, MFC. Ugh! Never mind.

If that sounds excactly right, well then you’re me and I want my body back, but if it sounds close to right then I have great news for you. RubyCocoa! Started by Fujimoto Hisa and continued on at http://rubycocoa.sourceforge.net, RubyCocoa allows you to make complete OS X applications in Ruby, using all the features of the Cocoa framework. There’s already a few applications out there in it, and a lot of great information, but what I found is that if you’re a complete newbie to Cocoa/OS X/Interface Builder and Objective-C like I was there’s no good step-by-step tutorial. Until now! (Tada!)

What the heck is Cocoa

Cocoa is an application framework for writing applications on OS X. That really doesn’t tell me much does it? How about a diagram:

[1]

It’s an application layer on the Mac OS, with all the pretty buttons, scrollbars, and other such widgets that you expect from OS X applications. These are used through the Objective-C classes included in the framework of your application. Wait, I know what you’re thinking, “C? Did you say C! Are you out of your mind? I’ve never been so lied to in my life!” Relax my friend and keep reading. I promise you there is no C in this tutorial, well except….

Objective-C

Objective-C is the preferred development language for applications on the OS X platform. It was originally developed by Brad Cox as an object-oriented extension to C, and is compiled in the gcc compiler. It’s primarily influenced by SmallTalk, much like Ruby. If you know C or C++, and really if you are over 25 and a programmer you probably do, then you should be able to learn Objective-C quickly. Fortunately you don’t, but you will need to understand some bits and pieces of the syntax in order to translate Cocoa documentation to Ruby. I’ll point out where this was done in the tutorial.

Getting RubyCocoa

You wanna write Cocoa apps in Ruby, you need RubyCocoa. All those Objective-C classes are available through Ruby calls, removing the need for such Objective-C necessities such as memory allocation and deallocation, keeping your code simple and beautiful. Guess you’re going to have to install it. Here’s the subversion call:

svn co https://rubycocoa.svn.sourceforge.net/svnroot/rubycocoa/trunk/src rubycocoa

Next we need to build and install ruby cocoa. You’ll need XCode installed for this to work, and for the rest of the tutorial to work. I’m assuming that you’ve been developing in Ruby for more than a few hours, so you’ve installed some gems. If so you probably already had to install XCode. If not then you’ll need to insert the OS X setup disc that came with your Mac and install it. I’ll wait. Sheesh that took a while. Next, from the directory where you checked out the source code, do the following:

$ ruby install.rb config $ ruby install.rb setup $ sudo ruby install.rb install

The preliminaries are over, let’s code.

Your first project

This is where the fun begins. We’re going to make an app together, and as we go I’ll explain the bits and pieces in baby steps. Afterwards hopefully you’ll know the basics of Cocoa as well as the basics of RubyCocoa. I’m borrowing liberally from the basic tutorial done in Objective-C on Apple’s developer website[2], only done entirely in Ruby. If you’ve got 20 minutes, you can do this tutorial. It takes a half-hour in Objective-C.

Sadly to start we need to use XCode. Maybe it’s me, and my bias against overcharged IDE’s, but I don’t like XCode. It’s awful busy, and it’s code formatting in Ruby is …well my mommy told me if you can’t say something nice don’t say anything at all. So start up XCode and choose File-> New Project. If you installed your RubyCocoa bundle properly you should be able to select Ruby-Cocoa application from the menu.

Create the Ruby-Cocoa application and name it Currency Converter. You can put it wherever you want. Once you’ve created it you should see this:

This is your XCode project, similar to a Visual Studio project for my fellow Windoze converts. The files you’ll be dealing with in this example are as follows:

• CurrencyConverterDemo.app. You may have named your project differently than I did, but this will be the name of the app file after it’s built. This app is distributable to anybody using Mac OS X just like any other application you might have built in Objective-C. You may be used to writing Ruby scripts that require the user to install various gems or a particular version of Ruby, but thanks to the RubyCocoa.framework also included in the default project this app can be distributed with your users unaware that what language you wrote it in.

• MainMenu.nib. You’ll be making this your friend. It’s where you create your interface, your interface objects, and instantiate them as well - assuming they are NSObjects. You’ll also setup actions, outlets, and bindings. I realize none of this makes sense yet, but bear with me. Double click the Nib file and you’ll open Interface Builder, where most of the action is.

Interface Builder and .nib files took a little getting used to for me, perhaps because of my time doing Windows development, because it’s similar to Windows Forms and Resource files while at the same time being completely different. When a Cocoa application is loaded the first thing it does is load the Nib file, and instantiate all the objects and variables you’ve setup. That’s right, instantiated objects in a GUI. There’s a lot more to this than just setting up how the application looks, you’re setting up objects and how they relate to each other too. If you’ve double clicked the Nib file then you should see four windows. The first we’ll be dealing with is the Main Menu.

Okay it’s not the best screenshot in the world. You’re not reading [coding horror] (http://www.codinghorror.com/), you’ll have to deal with it. The first thing to do is change the name to Currency Converter. Just double-click the name and it will open an editor for you, and you can do that. Single click the Menu title and you’ll see the drop-down menu. Edit that so that each name is also Currency Converter. Next we’ll setup the window. That’s this empty slate:

First things first, you don’t want to let our little app be called Window do you? You can’t double-click here, but you can use the Inspector. The Inspector shows you all the properties for whatever object you have selected in the application. This comes in real handy when you don’t know a keyboard shortcut. Hit Command-Shift-I to bring up the Inspector. That gives you this screen:

See that field that says Window Title - change it to Currency Converter as well. Let’s change the size too. In the Inspector click the drop-down window that says Attributes and select Size. In the Content Rectangle section there is a drop down box that says Width/Height and next to it two windows with Width and Height. Set the size to 400x200. That’s a pretty good starting point. We’ve got a blank window, think we could use some controls? See that big window on the right - the one that looks like this:

Yipee Toys! The screenshot above shows the Controls view, which isn’t actually what we want because we won’t be adding any buttons yet. We’re adding some text views. Along the top of the window are choices for the different types of Cocoa objects we can add to our application. Select this one: so we can start adding text objects to our window. First we will add three edit boxes. Simply take one of the empty edit boxes and drag it to your window. When you drag your Window over you’ll see blue lines appear. If you lock to those you can take a big step in meeting Apples User Interface guidelines.

You’ve added the first, but to make life easier on yourself hit Apple-D to make the other two. Make sure you align then on the right blue line, and you should also see a blue line on the top of each box, which marks equal spacing between each edit box. Next add the System Font Text to the left of each box. Add the first one to align with the top box, then again use Apple-D to duplicate them. Align them with each of the boxes, using the blue lines. It should look like this:

We aren’t exactly finished with our application yet are we? For starters we need to change that to useful text. Double click each text box and change the text to read Amount of Money:, Conversion Rate:, New Amount: respectively. Um - uh oh. This doesn’t look right does it?

We’re gonna have to fix that. Holding down the shift button click each box. This should select them all. Next choose Layout from the top menu, and choose Size To Fit. This will make all the boxes size to fit the text, and extend the top box to include the text you entered earlier. If any of your boxes are two lines long it’s because you added a return to the text when you edited it the first time. Go ahead and re-edit the text, deleting the return then size to fit the box again. Now select each text element individually, and head to the Inspector. It should already be open from previous uses but if not use Apple-Shift-I to open it up. Select the attributes for the text object in the drop-down and set the alignment to the right.

Once again select all the text boxes again making sure you start from Amount of Money:. Choose Layout-> Same Size. Then choose Layout->Alignment->Right edges. Drag all those boxes to the left side of the window, aligning with the blue line when it appears. I use the keyboard for this so that I don’t accidentally move the text up or down. Finally drag the edit boxes over to the text, again aligning with the blue line. You do this by selecting all of them, then moving them to the left. At this point the box should look like this:

Looks like it’s a little big, but we don’t want to resize it until we add our button. In the Cocoa window go back to the controls view. with this button: . Not surprisingly we’re going to add a button to the window, in order to actually convert the currency. Take the button and drag it over to the Window, putting it underneath the boxes and once again aligning with a blue line that will appear above it. Double click the button and rename it to Convert. Now let’s take a peek at one of the cool parts of Interface Builder. With the button selected, hold the option key and move your mouse over the box. You should see this:

Now by moving the keyboard left and right we can actually put the button directly in the middle of the three boxes. Now it’s time to shrink the screen to fit, just like you would shrink any window until the ever-so-ubiquitous blues appear. Do that now. Finally just for a flourish let’s add a little line between the button and the boxes. Drag the horizontal line from the controls on to the window right underneath the boxes, aligning with yet another blue line. Extend it to the blue lines on the left and right to make it full sized. You should have a dialog box that looks like this:

I swear we’re almost to Ruby code, so quit complaining and save your interface. We now need a way to interact with this pretty little picture. The way that’s done in the land of Cocoa is through Actions and Outlets. Actions are methods that can be triggered by other objects, whereas outlets are pointers to other objects. Essentially if you want to do_ something you need an action if you want to _set or get something you need an outlet. The first thing to setup is an action - the Convert button needs to _do_ something does it not? In order to connect the action from the button we need to have a class. That’s right - we’re going to make some Ruby code. There’s one more window we haven’t yet used in Interface Builder:

Click the Classes tab so we can crate two Ruby classes, both of which will inherit from NSObject. That’s right, Ruby classes inheriting from Objective-C classes. Like a Picasso it’s disturbing and beautiful at the same time. The Classes view lists all the available Cocoa classes, so scroll to the left side and select NSObject. Then hit enter and it will automatically create a class named ConverterController.

Now this creates a class in the Nib file so that the interface knows about it, but because we’re using Ruby we don’t actually generate our class from it. Let’s also create a class called Converter. Even though it’s overkill we’re going to create a MVC framework here, simply for demonstration purposes. After you’ve done that select ConverterController and use Apple-Shift-I to again bring up the inspector. You should see this view:

Let’s think for a moment. What is the controller going to need to do. When the button is clicked it needs to get the values for the original amount and conversion rate, calculate the new amount, then set the new amount. This means we will need:

• Action - for the convert button
• Outlet - for getting the original amount
• Outlet - for getting the conversion rate
• Outlet - for setting the new amount
• Outlet - for sending the data to the model to calculate the new amount.

Admit it, you were going to just do the calculation right then and there in the Controller class. Say 10 Hail Matz’s for punishment. Good job. Adding these outlets and actions is pretty self explanatory. Just click add. There’s one gotcha. The action is a method. Methods in Objective-C will have a colon at the end and you must have the colon at the end in your description of the outlet, even though the method you actually declare will not have one. Otherwise things won’t be found. When adding outlets there is a drop down for the type. This has a use in Objective-C, but we’re doing Ruby. Leave it at id.

What we’ve created here is a class definition, so that Objective-C can call the classes you haven’t implemented yet. However we also need to instantiate the class, otherwise there’s nothing to connect. Everything you’ve just defined is a variable, it needs to be set to something. To do that select ConverterController and select from the top-level menu Instantiate ConverterController. Then do the same for Converter. This lets the Cocoa Framework know that when it starts up it needs to create each of these objects. You won’t be calling new here, in fact you never define initialize or call new on a Ruby Cocoa object. That’s a topic for another day however. In the Instances view you should now see this:

I’m going to re-iterate something. These aren’t a resource file, or an XML definition. What you’ve done here is create real live objects. If you attempt to build and run now it will fail because you haven’t written an underlying implementation, but the objects are there. They will be allocated. They’re the real thing. Now look at that tiny exclamation point next to ConverterController. What it says is you have unconnected outlets. When the Cocoa application starts up it’s going to attempt to link those outlets and if you haven’t connected them they will be set to nil. Let’s connect them. To connect a control to an action you hold the Ctrl key and drag from the button to the class. Think of the connections as following the path of the event, so for example you’ll drag from the Convert button to the class that will implement the action: ConverterController. When you do that the Inspector will display automatically with the convert: action highlighted. On the bottom of that dialog click connect. It should look something like this:

You’ve connected your first action to its target. Now when you click Convert the action convert in the ConverterController class will be called. It’s time to go the other way. Ctrl-drag another line from the ConverterController to the first edit box and connect it to the appropriate outlet. Do the same with the other two edit boxes. You should see this in the Inspector window:

One more to go. You don’t have to go from an instantiated class to an object in the window, you can go from object to object right in the Instances view. Let’s do that now to connect the ConverterController to the Converter object, and you’ve got your final outlet. Save your Nib file, and go to the XCode window. On the top window go ahead and click the Build and Go button. The application should start up just fine displaying your new shiny dialog. If you click Convert it does absolutely nothing, say it again. Yea! We get to write Ruby code to implement those classes now. About time isn’t it? In the action drop down select New File. In the New file dialog make sure you select Ruby NSObject class like so:

Create converter_controller.rb and converter.rb. Both these will be opened for you in XCode, but I prefer to open the project at this point in Textmate. Either way your will begin editing your Ruby code. Let’s start with the Converter Controller class. First things first we’ll delete the boilerplate comments and the require, which is unnecessary. Next we better rename that class to CurrencyConverter and converter to Converter. Don’t blame me, XCode doesn’t know much about Ruby and has no idea about naming rules. Now we need to implement those outlets and actions and it couldn’t be easier. First the outlets. Where you would normally type attr declarations and the like add this:

ib_outlets :amount_of_money, :conversion_rate, :converter, :new_amount

I know I know, it’s not DRY. I’m sorry but Interface Builder does not support generating this code from the GUI with Ruby, at least not yet. Next the action. Create an empty method named convert. Done! For some perspective in Objective-C you would have had to define this in the interface, with the proper macro, then implement it in the implementation file. Sure it’s a few more lines, but you’re a Ruby programmer so you know just how much nicer four lines can be, especially when you keep adding them up over the course of an entire project. Build and run your project again. It will still do a whole lotta nuthin’, but the console won’t show any errors about being unable to find CurrencyConverter or Converter. If you get errors that classnames must be constant it’s because you forgot to rename the classnames. You’ve got an implementation ready to be written, and you can add the code. Let’s go into your convert action and get the values from the outlets that will have the user type in. Add this to your class:

def convert
  amount_of_money = @amount_of_money.floatValue
  conversion_rate = @conversion_rate.floatValue
end

I know I’m an idiot right? There’s no initialize method so the outlets are both nil. Okay you got me, so how come when you build and run this the app doesn’t crash? Try it now. Build your new app and add values to those two boxes, then hit convert. Did it crash? It didn’t? Then I expect an e-mail apology for those nasty thoughts you had about me. The reason it didn’t crash is because of the way Cocoa works. On the start of your application it instantiated the classes necessary and setup all the outlets with the values you specified in the Nib file. In fact if you were to add an initialize this code wouldn’t work, because RubyCocoa does not even allow initialize in classes that inherit from Cocoa classes. The reason for this is that Cocoa doesn’t have initialize, it has alloc and init. You can instantiate your own class, and you should for testing, but don’t use initialize.

There’s one other thing funny about the code, and that is the name floatValue. Unfortunately Objective-C methods use camelcase. I wish RubyCocoa rubified the names, however on the bright side every time you see that naming convention you should be able to instantaneously identify it. Cocoa object here! Our object still doesn’t convert anything, so let’s finish off the controller’s implementation. Add the calculation and the setting here:

def convert
  amount_of_money = @amount_of_money.floatValue
  conversion_rate = @conversion_rate.floatValue

  new_amount = @converter.convert amount_of_money, conversion_rate

  @new_amount.setFloatValue new_amount
  @amount_of_money.selectText @amount_of_money
end

Reads pretty darn well doesn’t it? Get a float value out of the amount of money and conversion rate boxes, use the converter object to then convert that to a new amount, then set the float value for the new amount. Finally we select the text to the amount of money dialog box, so that we can calculate again. I realize I’m explaining method calls very quickly, but I’m not sure there’s that much to say. Compare this to the Objective-C version:

#import "ConverterController.h"

@implementation ConverterController

- (IBAction)convert:(id)sender
{
    float rate, currency, amount;

    currency = [dollarField floatValue];
    rate =     [rateField floatValue];
    amount =   [converter convertCurrency:currency atRate:rate];

    [amountField setFloatValue:amount];
    [rateField selectText:self];
}

@end

Honestly that’s not even fair to the Ruby version, since I could easily shrink down the calls to get that method into two lines and I didn’t display the header file for ConverterController. Finally let’s write the one-line implementation of the converter model:

def convert(amount, rate)
  return amount * rate
end

We’re done! Look at that, 90% of the work was getting used to interface builder. Build and run your app. Yipee! You can convert currency now. You’re a God. Well at least a demi-god, like Heracles. Here’s hoping this can be a series of articles, and that you keep coming back for more.

* Footnotes * [1] http://developer.apple.com/documentation/Cocoa/Conceptual/CocoaFundamentals/WhatIsCocoa/chapter2section2.html#//appleref/doc/uid/TP40002974-CH3-DontLinkElementID_20 [2] http://developer.apple.com/documentation/Cocoa/Conceptual/ObjCTutorial/

This article is largely a conglomeration of other sources and could not have been completed without the following: Aaron Hillegass’s excellent Cocoa Programming for Mac OS X, RubyCocoa.com, the Apple developer website, and of course http://rubycocoa.sourceforge.net. I wholeheartedly recommend going through Aaron’s book, using Ruby as your chosen language. You’ll be amazed at how fast you can translate the code.

That's Not Agile!

by: doug | August 5th, 2007 | 4 comments »

Removing the religion from software development

I had feared those words. I’d often been tempted to use them myself, but something told me I shouldn’t. As I sat in a planning game on a previous job, I heard the words. They still make me cringe. “We can’t do it that way. That’s not Agile.”

I’m a big fan of agile. I’ve long been convinced that the agile movement truly is uncovering ways to do software better. It’s revolutionizing the way that companies approach software. At 8th Light we’re using Agile to help us deliver the highest quality software possible to our clients. I wonder though, how exactly something can be classified as un-agile?

What is Agile anyway? Can it be measured? Can one thing really be more agile than another? If I had a yardstick and I was going to measure Agile, what would the markings be along the stick? What units would I use? ‘Points’ has already been taken, so maybe I should invent a new unit. I’ll call it the Agl. For every hour of pair programming an organization does it gets 10 Agls. Unit tests are worth 1 Agl each. Acceptance tests get 100 Agls. I’d use negative values too. For every page of documentation written, an organization looses 40 Agls, but the group running in iterations gets 1000 Agls. One week iterations are worth 2000.

The problem is that as a development organization adopts Agile and buys into various processes and practices, the temptation quickly grows to covert that development process into religion. “We can’t do code reviews, that’s not Agile!” “We don’t write documents, that not Agile!” What may start as genuine excitement and passion can quickly become religious dogma when those involved in the process lose sight of why they do what they do. Let me say that while I am a religious guy, I hate religion. Religion, to me, means action without thought: doing or saying something because that is the thing that you are supposed to say or do. I’d rather call what I have faith. Faith comes from beliefs or values held and turned into day-to-day living.

Since we are talking about religion, I thought I story from the Bible might be appropriate. Jesus and some friends were sitting down to eat when some super-religious folks showed up and started berating Jesus for letting his friends eat with dirty hands. These religious-types had established an elaborate ceremony for washing hands that had very little to do with removing bacteria. Jesus comes down hard on these guys for exchanging true principles for religious dogma. He responds by handing them the principle that does really matter. “Nothing outside a man can make him ‘unclean’ by going into him. Rather, it is what comes out of a man that makes him ‘unclean.’ ” (1) Here one of the most well-known religious leaders of all time shows his followers that it is the true principles that matter, not the religious practices or rules.

In software planning situations and day to day development we are faced with hundreds of little decisions about how to do our work. Should we throw this code out and start building the whole thing from scratch? Should we iteratively improve the code and slowly arrive at a better design? Do I write a test for this code? Should I pair with someone or just write this myself? When making these decisions we need guidance, something to help us understand if one thing is better than another. “Agile” is not that thing. Agile is just the label put on a whole spectrum of practices. Those guiding lights we need are principles. Principles are the domain-specific set of beliefs that an organization has adopted. They reflect what the organization values. I think it’s possible that many organizations get swept up in the excitement and freedom of agile practices that they skip this critical step of establishing the their principles. Kent Beck lays out a set of principles for extreme programming. Baby Steps, Failure, Quality, Redundancy, Opportunity, Flow, Reflections, Diversity, Improvement, Self-Similarity, Mutual Benefit, Economics, and Humanity(2) help direct an organization when it is trying to figure out the how of software development. Whenever I’ve heard Kent speak, he always comes back to the principles and values behind the practices in extreme programming. UncleBob has established a great set of principles that help us discuss and qualify designs. The Single Responsibility Principle, the Open-Closed Principle, the Don’t Repeat Yourself Principle(3), and others are guiding lights for design decisions. These give teams concrete evaluators that keep design discussions productive and prevent them from deteriorating into contests of dogma. Alistair Cockburn writes about 7 properties in Crystal Clear that can be translated into principles: Frequent Delivery, Reflective Improvement, Osmotic Communication, Personal Safety, Focus, East Access to Expert Users, Automated Tests, Configuration Management, and Frequent Integration (4). I don’t want to delve too deeply into these principles here, but an organization in the process of adopting agile should. Each of these manifesto-signing authors have explained these principles wonderfully in their books.

At issue in my planning meeting was whether or not to require a certain feature in a third party library for which we are shopping. At the time, we didn’t have a need for this feature, but we anticipated that it may show up an upcoming story. The person who spoke up saying “That’s Not Agile”” was really referencing the XP value of simplicity. “Solve today’s problems today and tomorrow’s problems tomorrow.”(2) This would suggest that one shouldn’t take on additional complexity until it is needed. However, when purchasing a third party library, perhaps the principle of Economics might suggest that paying a little more for this library today will save a lot of time and money later and potentially avoid purchasing the library twice. Which is the right decision? I don’t know, but after having agreed on the principles that guide our decisions, we can have the conversations around those principles and pick a way forward.

An organization transitioning to some flavor of agile ought to first clarify what its organization’s principles are. Read Beck or Martin or Cockburn or your favorite Agile author and choose the principles that you want to live by. Second, make the principles visible. Put them up on a wall. Have meetings where team members present a principle. Refer to them as you pair. Write about them, read about them, explore them. At 8th Light, we’ve put them on our website. Revisit them when starting a new project. If you are working with a consultant, ask them to take you through a values and principles exercise. If you are a consultant, please don’t miss this critical part of transitioning to Agile. Making your principles part of the every day vernacular of your organization will take you to a place where design and planning discussions stay productive and you’ll hopefully never hear “That’s not Agile!” again.

End Notes:
1) Mark 7:1-16
2) Beck, Kent. Extreme Programming Explained: Embrace Change (2nd Edition). Addison-Wesley Professional. 2004.
3) Martin, Robert C. Agile Software Development, Principles, Patterns, and Practices. Prentice Hall. 2002.
4) Cockburn, Alistar. Crystal Clear: A Human-Powered Methodology for Small Teams Addison-Wesley Professional. 2004.

###