Alieniloquent

I came across this amusing (fictional) story about a broken watch, and it’s impact on the author’s development process.

I particularly liked one of the author’s comments in the comment thread:

Velocity is a measurement that comes out of development, not an input that goes into it.

[Uncle Bob] said . . . that when you are trying to measure something, it’s counter-productive to put pressure on it.

James Golick writes about crunch mode and how it can turn a team of even the best all-star code artists in to mediocre programmers.

I have been on an agile team full of all-star programmers. Every one of them as bright as the sun, and every one of them dedicated to writing quality software. Sure, we inherited a legacy code base of nearly a million lines of not-so-all-star code, but that’s the same situation everybody else is in too, right? It took us a couple of years to really get the agile juices flowing, but once we did, it was great. Except for crunch mode.

I’ve seen what James is talking about first hand. I’ve been what James is talking about. What I’ve never understood is why crunch mode seems more appealing to managers than facilitating the things a team needs to truly deliver on the promise of constantly shippable code. To me, the value proposition of being able to ship after any week- or month-long iteration is a big win over going into crunch mode to hit a date.

But I’m a developer, what do I know about managing projects, right?

So I decided to start a pod cast. Check it out: The Agile Mac.

So I’ve been thinking about starting some sort of periodic content: perhaps a regular themed article here or a podcast. I would like to take advantage of what readers I do have to see what people would like to hear me talk about.

Here are some topics that I’ve thought about doing:

• Things about programming they don’t teach you in college
• Agile methods
• Test-first design
• Refactoring
• Cocoa programming
• Ruby programming
• Lisp programming

There’s no particular order to those, as I find them all very interesting. It’s possible that I could end up doing a mishmash of all of them.

Please leave a comment with a topic you’d like to hear me talk about!

In my previous post I talked about this problem I ran into with byte-ordering and tests failing. Brian and Joe both felt that I left them hanging by going into all the technical details of what my problem was and not going into the technical details of why I shouldn’t have used htons to start with. Rather than editing the other post, here’s a new one.

The code that I was using htons in was my SOCKS5 implementation. For those who aren’t familiar with SOCKS5, it is a proxying protocol. The computer connects to the proxy and sends it a hostname and port for the actual connection. The proxy then makes the connection and relays packets for the remainder of the session.

Some of you may be guessing what I was calling htons on already: the port to be serialized. Here are the two offending lines of code:

That buffer was then, in turn, written out across the socket to the server (or inspected by unit tests). But, since I was extracting each byte individually the byte-order didn’t matter since 0xFF00 will be in the same byte order as port every time.

I hope this explains things a little better.

So I have this project, and it compiles for the Mac on both PPC and i386 architectures. Naturally, I have unit tests for this project.

One of the things that I’ve had to write for this is a simple SOCKS5 implementation (because of issues with Apple’s implementation). As part of this I had to do some manipulation of a port number and get the high and low bytes.

I’ve done this sort of thing before. That’s what htons and friends are for. So naturally, I went ahead and put this in where I thought it mattered and went on my merry way. On my ppc powerbook, my tests all passed.

Yesterday, when I ran the unit tests on my intel mac for the first time, I discovered that a test failed. It was failing because of some byte-order problem. After troubleshooting it, I narrowed it down to the htons calls. It turns out I did not need them.

See the thing is, on a ppc, things are already in network byte-order so htons does absolutely nothing. However, on i386 host byte-order is different from network byte-order. So the reason it worked on ppc was that it was essentially as if I hadn’t done it.

It turns out that the particular thing I was doing didn’t need the conversion to work correctly. I removed it, and everything worked peachy on both machines.

Blaine has a post about how strings are so frequently abused in object models. We heap extra meaning onto a string when we really should make a class. The reason we should make a new class is that each class represents a concept in our domain, and we can add behaviours and data to each class. You’ll be hard pressed to do that with a string. So, to stay agile it’s better to make new classes for new concepts.

In Delphi, there’s a similarly abused syntax trick. It looks like this:

Then, wherever you want to get a string associated with one of the enum tokens, you can just index into that constant array using the enum value.

This trick isn’t limited to arrays of strings, either. You could have arrays of integers, doubles, characters, or even objects, and you can make as many of these arrays as possible. So if you have some setting and there’s ten values that change with that setting, then you could have the setting be an enumeration and have ten constant arrays indexed on that.

In a world of procedural programming, that’s a neat trick, and it can help a lot. But Delphi shed it’s procedural shackles years ago, and now it has the power of objects to help it out. Sadly, many programmers are tied to Delphi’s procedural roots, and can’t get away from this enumeration-indexed array trick.

What’s so bad about the trick? For starters, you’re making global data. Sure, it’s constant data, but it’s global, which makes finding where the data is coming from that much harder for somebody new to the code (or somebody reading it months after they wrote it). Secondly, in order to vary behavior based on the enumeration, you have to have gnarly conditionals that branch based on the type code. This makes methods longer and harder to understand and follow. Lastly, it makes the types more resistant to change, especially if they’re serialized as integers: any change in order will change the ordinal (integer) value of the same enumerated value.

What’s the alternative? Make a class. You can easily make a class that represents the type code, and you can make subclasses for each type. The class can have methods for each of the constant arrays and the subclasses can implement them to return the proper ordering. If there’s behavior specific to one type you can put it on this class hierarchy and polymorphically switch out behaviors, instead of making gnarly conditionals. Moreover, there’s no inherent ordering from one class to the next, so you can completely control how things are serialized and compared.

As Joshua Kerievsky says in his book Refactoring to Patterns, so many developers have an obsession with using language primitives such as strings, integers, or enumerations. Whether that’s because they think that it’s too much work to make a class, or it’ll take too many CPU cycles, or it’ll eat up too much memory, it doesn’t matter. The obsession with primitives is unhealthy and it leads to spaghetti code that is hard to refactor.

We must resist the temptation and make supple, agile code. That means we must make classes.

There’s plenty of articles out there telling you how to use OCUnit, especially now that it ships with XCode 2.0. They’re all excellent. You should read them, especially Apple’s. This article is simply about a little trick that I’ve come up with to solve a minor annoyance I have with using Apple’s method of hooking up what they call a dependent test bundle.

A dependent test bundle is a really neat idea, actually. It uses your actual application as a framework at link time and then uses some nifty magic to launch the test bundle from inside your application and run all of the tests. Why bother with all of that? It means you can keep your application code in one target and your test code in another target — completely separate. That’s a worthy goal.

The only thing I don’t like about this, though, is that if you’re developing a GUI Cocoa application (and let’s face it, most people are) then the process of running the tests from within the application has the consequence of popping up the GUI and letting it sit there until you quit manually. That’s annoying.

So I came up with a solution. It’s really nothing that fancy, but I thought I’d share. I make a Cocoa Shell Tool target, and I name it something like stub. I make a C file and name it stub-main.m. In that file I put the following three lines:

Then I add all of the application source files that my tests are going to need to link to and make sure it all compiles. I just use that as the bundle loader for my tests, and it’s all good. No GUI popping up.

For an example of how to do this, you can look at the source for OCFit.

So I was looking at a C# class that looked something like this:

Now that smells to me. Take a moment and see if you can sniff it out. I’ll wait.

That’s right. We’re passing in bar and then also passing in something that we use bar to get. But that’s not all. I didn’t show it in the snippet, but inside Foo the way we use the BazCollection is also indexed by bar. So, we have this object and sometimes it indexes into a collection and sometimes the objects that construct it index into a collection for it. The responsibilities are muddled. Sometimes a Foo indexes in and sometimes it doesn’t.

The power that objects give us is to wrap up data and the responsibilities associated with that data into a nice little bundle. That power doesn’t do us a lot of good, though, if we don’t actually use it. In a case like this the responsibility of which object should be indexing into the collection is spread onto two objects, and only should be in one.

Now, one refactor that we could do would be to just pass the collection in for the Qux as well:

This refactor is not the one I would choose, though, as now it is even more complicated to construct a Foo. Specifically if I want to test my Foo (which I do, of course). The foo is only ever interested in a single Baz and a single Qux, so it’s just extra overhead to have to create a collection for each. That brings me to the next refactoring that I might try:

This has the advantage of making Foo’s responsibility very clear. It is meant to bring the bar, baz, and qux together. But, that call-site still stinks. In fact, it reeks more with that original odor. At this point, it would be worthwhile to see what Foo actually needs the Bar for and further factor that out. Maybe we can have something like this:

That way we remove the dependence on Bar completely from the Foo, and push it into the FooFactory. Maybe we will create an object that encapsulates those parameters. In fact, maybe this factory is that object. But one thing is for sure, this code is better separated and easier to test and use than the original.

A link to an article titled, “Agile Programming: How to doom your software project” by Steve Friedl was pasted into my IM window this evening. Steve wrote an excellent piece about being a consultant back in January, and I enjoyed it quite thoroughly.

Seeing as I work in an agile shop, I was drawn to the title of this article like a moth to a flame. It seems that Steve found the agile manifesto, and misunderstood each line item. Now, it’s really not his fault. The manifesto could use a companion document that explains it, or perhaps it should be rewritten such that it elaborates. But, the end result was that Steve came away thinking that all of us agile guys have had a bunch of kool-aid and are about to plunge our companies into deep pits of failure with these kooky ideas. This just isn’t true (well, except the kool-aid, but I mean, that talking pitcher is just so charismatic, I have to drink from its head). So I am here to explain the four points and hopefully allay any misconceptions you might have about them.

“[We value] individuals and interactions over processes and tools”

Steve seems to interpret this to mean that agile practitioners would rather throw people at a problem than find a good tool for it. That is simply not true. Even cursory research into agile practices (including surfing the Agile Alliance, which Steve linked) would reveal a heavy preference toward tool usage. In fact, agile practitioners strive to automate as much as they can so that they can focus on the hard problems.

The idea behind this principle is that our teams should place a higher value on our people than on which tools or processes that we use. The people that comprise a team are the most expensive, and most valuable resources that the business will put into producing software, and so it is important that they are valued. Individuals should be given the power to get things done the best way that they can. They should be given a license to be creative and innovate.

The people on a software team are the most important part. If the tools are getting in the way, then they need to be replaced. If the process is slowing things down, then it needs to be revised. Tools and processes are a means for the people on the team to get to and end. Each engineer should be able to get to those ends by the best, most efficient way they can.

Steve also says that in his experience, “a lot more projects have been sunk by not-enough-tools than by not-enough-interaction.” I’d wager that when he thinks of interaction, he thinks of meetings that last hours–nearly useless meetings that mostly serve to bore all those in attendance. That is, indeed, not going to help a project succeed. Thankfully, that’s not what agile practioners mean.

Agile practioners realize that developing software is not a technical business, at its core. It is a social business. It is about providing people a way to do something that they couldn’t do before. It is about making things easier for people to do. It is about enabling people to interact with technology.

At its core, software is all about individuals and interactions. Whether its a user interacting with his computer, a salesperson interacting with her client, a programmer interacting with his customer, or a programmer interacting with the code, software is all about individuals and interactions. Agile practitioners realize this and strive to make the interactions efficient and enjoyable so that the individuals can do more and enjoy themselves.

“[We value] working software over comprehensive documentation”

This is an easy one to misunderstand, and maybe Steve didn’t. There are two schools of thought when it comes to specifications: they are either redundant information that is duplicated in the code, or they are essential tools to communicating what the software is supposed to do. Whether or not Steve understood the manifesto, he clearly adheres to the latter school.

Agile practitioners realized that they were writing documentation that described how the program was supposed to behave and then they were writing code that described how the program was supposed to behave. Yes, you read that correctly. That is all code is: a description of how the program is supposed to behave. It’s expressed in very precise terms with very specific grammar, but it is a description of the program’s behaviour nonetheless.

What’s more, because we’re writing everything down twice (or more, depending on your process), there are two (or more) places that have to change if those behaviours have to change. And, unless you’ve got some magic voo-doo that I don’t know about, there’s nothing that forces you to keep your documentation in sync (even the best literate code tools don’t care if your documentation comments are out of sync with the real behavior).

The solution is to make your specification out of code. Write tests using technical-facing tools like these and write tests using business-facing tools like this. Use these tests to specify exactly what the behavior is: if the tests pass, the program works. What’s more, these tests actually use the code and inspect its behavior. So, if its behavior changes, the tests will know automatically. Furthermore, the tests serve as examples of how to use the code. With tests like these, you don’t really need a specification document anymore.

We all know that we should strive to remove duplication from our code. That’s why we refactor and that’s why we design. Agile practitioners strive to remove duplication from our processes as well. The less we duplicate information, the more efficiently we can change and the more quality those changes will have. This is what we mean when we say we value working software over comprehensive documentation.

“[We value] customer collaboration over contract negotiation.”

Steve’s right. Customers never know what they want. What he’s wrong about is that negotiating a contract up-front is the way to find out what they want. The truth is that the only way for a customer to find out what they want, and more importantly what they need, is to use the software. This is why agile teams place such a high priority on delivering working software quickly.

What’s more, agile teams tend to deliver their software in small increments and put in the features that are the absolutely most important first. I bet that if you asked a customer to come up with the list of features that would have to be in the product to make it have any business value at all, they wouldn’t have a hard time (”a text editor must be able to display text files, change text, and save text files”). Once you have this super-simple, barely valuable product in the customer’s hands they can give you good feedback as to what should go in next. Working this way, the customer gets exactly what they need and they get it as quickly as they can. It also allows their understanding of what they need to grow while they have a working program.

Give me a customer who wouldn’t want to have a working program that delivers business value after two or three weeks, and I’ll eat the paper you printed this out on (assuming, of course, you printed this out).

“[We value] responding to change over following a plan”

Steve returns once again to software specifications. We know what agile practitioners think of duplicating data, but that is all about documenting what the software does. How are we supposed to decide how to get from now to a time when it does these things? We plan. But built into that plan is the expectation of change.

Agile methods build in the assumption that change will happen and it will happen often. So Steve’s sentiment that “hopefully one has built a [software] system that tolerates change,” is reduced to “one built a software system that tolerates change.” Assume that there will be technical changes and ensure that your software is easy to change by keeping it well factored and easy to understand. Assume that there will be business changes so deliver software in short cycles.

Agile software development is all about embracing change and expecting it. As the old adage goes: the only constant thing in software is change. Learn it, love it, live it.

I’m certainly not the first person to say these things, and I probably won’t be the last. I hope reading this has shed a little light on what that manifesto really means, but the best way is to get out there and do it. Try an agile method on a project and see how you like it. If it works for you, great. If it doesn’t work for you, great, now you know. Sitting around and speculating gets you nowhere.