clog

When running the 64bit kernel in Snow Leopard, TextMate will fail to execute most scripts.

This produces the following error for me (in the case of a Ruby script):

I was able to "fix" it by commenting out line 169 in:

/Applications/TextMate.app/Contents/SharedSupport/Support/lib/tm/process.rb

I haven't noticed any adverse affects (yet).

There are several schools of thought regarding how to best write user stories. There also seems to be a great deal of confusion regarding how stories are set up - probably because any research into the topic yields such a variety of opinions. Most of us (like myself) also come from a background that emphasizes technical requirements. Stories should emphasize "business success criteria" rather than technical requirements.

What is Business Success Criteria?

I know this sounds like marketing-speak but there's a reason for the semantics. A requirement can exist for any number of reasons. They may be politically motivated or part of another agenda. A requirement may be good or bad. We shouldn't assume that doing what we're "required" to do will lead to success. This doesn't mean anarchy is the answer either, the point is to succeed through collaboration.

You can call it Business Success Criteria, Success Criteria or Business Criteria (sometimes also called Acceptance Criteria). The point is always the same - to describe a path to success. A direction the project can go. There can be several ways to succeed but all "Success Criteria" should point to a consistent goal. If that goal needs to change then the criteria will also need to change. Stories should describe what it will take for a particular piece of functionality to contribute to the success of the business. Usually this is on a small scale at the story level. These small successes add up to successful features which add up to successful products which add up to successful businesses.

Breaking it into Pieces

Story writing usually starts at the feature level. With a set of large stories (sometimes epics) that are usually fully completed features. Most stories should not be fully complete features. These features should be broken up into several stories. Each story can be described as a minimal sub-component that still retains business value (meeting a small but essential set of business success criteria). Creating a new method for a class for example does not measure progress towards meeting business needs. The ability to create a new user, or the ability to modify that user for an application may both provide small yet essential functionality to the product.

Notice that these two items are mentioned separately. Rather than create a "User Manipulation" story there is a story for "Create User" and a story for "Edit User." You can think of these as contributing to a "User Manipulation" feature. Creating a user provides a small amount of business value, editing a user adds a little more. The code paths related to creating and editing are usually very similar (most likely with several shared pieces). They may even be identical, or use fancy metaprogramming for improved architecture. The best architectural solution is the way to go but from the standpoint of describing the business criteria these still are separate scenarios (or sets of scenarios) each providing their own value.

Duplication of Scenario Steps is not Necessarily a Problem Here

The steps involved with validating these scenarios may be nearly identical. That's OK! Duplication in (story) scenario steps is not such a big deal and many argue that it's actually a good thing. Scenarios should be as self-descriptive as possible, so copy/pasted steps may be just what you need. They shouldn't be superfluous however.

If stories are integrated with your acceptance testing framework you should avoid excessive use of metapgrogramming. Being DRY is still good but scenarios should be easy to understand. Scenarios should be clear and concise. The balance doesn't have to be perfect. Remember, you could spend all of your time architecting your test framework but keep in mind the point is to architect the application. At some point the essential specs and scenarios are in place so move on. If you're following Behavior Driven Development then your story scenarios and specs validate your success criteria and communicates how your system works.

As a side note. If you're writing effective tests, compare the amount of time you spend writing tests to the amount of time other projects spend adding bug fixes and the amount of time they require for integration. Which do you think is a more valuable way to spend your time? Would you rather write tests or create emergency patches? One approach requires more discipline but may be more enjoyable in the long run.

Human-Readable Specs and Scenarios

Your stories serve as a communication point between business and development. They should make sense to both developers and the business. Story Acceptance Tests should document the interface of all of the system components. The "Specs" (unit tests for the pre-agile) should describe the inner workings. Think of this as API documentation that a business person could make some sense out of, but more likely to be read by a developer that is new to the system. Sometimes (especially for large/difficult features) you need to describe a component that lies in the middle. This is similar to functional testing. In these cases you can validate functional components using your story testing. These are story tests that are "gray box." You peak into the internals a little but no more than possible. You should not use stubs or mocks for these. These stories should be used with care because they are describing technical aspects of the project. They should be relatively rare.

Tasks or Sub-Stories?

If you follow standard Scrum as defined in works such as "From the Trenches" then your stories may be more like the features I describe above which become broken into several separate tasks.

Advantages of doing it this way are that stories stay "pure." You don't have to worry about technical leakage into stories because these become technical tasks (but then you need to ensure that these tasks aren't superfluous). You can also have separate individuals working on different technical aspects of the story. This may or may not be a good thing. I usually think of it as a bad thing - preferring pairing and approaches involving more collaboration. Sometimes it's an unavoidable project requirement. Tasking may be a better approach for these projects. It also takes less time to write the stories themselves since you don't need to worry about many details. Downsides of tasking are that stories tend to be too large, making estimation less accurate and producing less detailed documentation. Tasks also tend to be redundant, with many smaller stories requiring the same tasks (create a model, create a controller etc). Large/difficult stories involve extensive time in the tasking phase, which can make IPMs drag on for a very long time.

Breaking stories up into sub-stories (creating the feature/story relationship) addresses the disadvantages of tasking but introduces some of its own. Note that the tasking method still involves the breaking up of "epics" just not to the same level of detail. When using this method, almost every story ends up being broken into smaller sub-stories. Story writing takes more time up front since there is more detail at the story level. It's hard to assign more than one person to a small story unless they pair. Stories are usually easier to estimate and track. Less time is spent in analysis during IPMs. Testing is usually easier since they are more targeted (despite the need to test more stories). There is a point of diminishing returns, however, regarding the reasonable lower limit of a story size. I prefer a typical story size that is either a single work-day or half a work-day to complete. Sometimes exceptions are necessary but they should be rare.

Start at the Beginning

If you are on a project that is completely new to Agile then I recommend starting with the reference scrum standard. Only start modifying your workflow/practices as you begin to understand the core concepts of Agile Development, which take much longer to sink in than you think. Most people tend to think in terms of processes rather than practices. This is the wrong approach. Often, when I outline a development workflow to management they don't see it as a workflow at all due to the exceptionally low process. It is much better when good practice keeps the process in check, rather than the other way around. An experienced agile coach can help a project or organization be as agile as possible while still recognizing business realities.

Nothing is Perfect

There is no perfect way to define success criteria, prepare for development, to ensure 100% success or revenue return on the product itself. Inevitably you will run into epics that are difficult to break apart or success criteria that are a little too technical. At some point the rubber needs to meet the road. Give it your best and fix problems along the way. The idea is to have efficient, sustainable and enjoyable development.

For an explanation of how stories should be narrated and scenarios written, the following blog by Dan North is a good description. There are some slightly different approaches out there. Cucumber adopts the "In order to x" style of narrative which puts the emphases on the reason where Dan North describes the "As a x" style of narrative which emphasizes the user. Since the concept of "all stories need a reason" is so important to agile techniques I prefer the "In order to" syntax. The essentials are the same though. There's also a stronger emphasis on shorter stories like I described above now - but the rest should help fill in the blanks.

mysqldump -u USER -p PASS -h HOST > clog.mysql

[BUG] cross-thread violation of rb_gc()
ruby 1.8.6 (2008-08-11) [universal-darwin9.0]

script/console production

>> Sidebar.all
ActiveRecord::SubclassNotFound: The single-table inheritance mechanism failed to locate the subclass: 'AimpresenceSidebar'. This error is raised because the column 'type' is reserved for storing the class in case of inheritance. Please rename this column if you didn't intend it to be used for storing the inheritance class or overwrite Sidebar.inheritance_column to use another column for that information.

>> class AimpresenceSidebar < Sidebar
>> end
=> nil

Sidebar.find(:all, :order => 'active_position ASC', :limit => 4).last.destroy

Following directions I found here:

http://mkoga.wordpress.com/2008/09/09/zsh-tab-completion-fix-for-subversion-15/

I was finally able to fix the extremely annoying ZSH+SVN tab completion bug.

I have zsh installed via ports so I copied the subversion file to: /opt/local/share/zsh/4.2.7/functions/subversion

Now I finally have tab completion back.. happiness

If you want to use a stable branch of rails as a submodule (rather than edge rails) use:

mkdir -p application/vendor
git init
git submodule add git://github.com/rails/rails.git vendor/rails -b 2-3-stable
git commit -m "rails 2.3 stable submodule"
ruby vendor/rails/railties/bin/rails .
rm -rf log/* tmp/*
git add *
git commit -m "initial rails app"

I’ve worked with Java to Ruby converts for the past year and the #1 thing that comes up over and over is the excessive use of inheritance. I can understand why, I was taught Object Oriented Programming in C++. We spent a week on encapsulation (that was the end of “basic” programming) and en entire semester on inheritance and templating (that was the “advanced” class). Inheritance was driven into so many of our heads that we have a hard time not using it. We were told that this is where the power of OOP lies - this is how you get the most code reuse.

Unfortunately it’s just not true. The use of inheritance results in very strong coupling of your code. Any class is dependent on all of its superclasses. You can’t isolate this class without taking all of the superclasses with it. You can’t isolate the classes’ siblings without doing the same. You either have to make several copies of these classes (don’t do that…) or you have to move the entire chunk of code from project to project as a single unit. The latter is the only practical choice you have - but what if you just want to use a few pieces of functionality found in this code? Tough luck - it’s all or nothing. This leads to bloated code, poor code re-use, and hard to use APIs. Ironically this is what most of us are used to - so it seems normal to us when we come across it.

Since publishing is a large part of the industry I work in, there are often “publishing” methods that need to be added to our models. Every implementation I’ve seen so far injects a Publish class in between ActiveRecord and the model. This isn’t necessarily a bad thing on its own. With just one level of inheritance we can still achieve good code reuse. But where do go from here? If we want to add additional functionality at this stage we either need to add it all to Publish (even if it’s not in the publishing domain) or we need to add additional levels of inheritance. All of the sudden our code reuse has gone out the window. We’re going to have a hard time injecting this functionality into other code bases.

Using composite objects instead of inheritance can help in many cases. We can add the desired functionality into a separate class and then instantiate that class in the class we want to “extend.” Then you can call (or delegate to) these methods.

def Publish < ActiveRecord::Base belongs_to :article end

def before_save raise Publish::NotPublished unless @publish.is_published? end end

Wow this still sucks! We either have to use two tables in the database or initialize publish from data in the article table. Either way really sucks. We don’t want to require an additional table and relationship. We also don’t want data for the Publish model in the Article table. Composition will often work just fine in a class that isn’t doing any object-relation mapping - but in this case it causes more problems than it solves.

In the land of dynamic languages (like Ruby) we can get around this. Using a run-time patch that injects a decorator method into a class can provide a way to build up functionality on the fly. It can also be more descriptive. It’s not always clear what superclasses Publish is being built from. If you break all of this functionality out into modules that get mixed in via decorator methods - then it’s easy to see what the behavior of the class will be by just looking at the class definition.

This functionality is broken out into a Rails plugin that allows runtime changes to ActiveRecord (or ActiveResource). Here is what the (simplified) patch looks like:

module ActiveResource module Acts module Publishable def self.included(base) base.extend(ClassMethods) end

  module ClassMethods

    def acts_as_publishable(options={})    
      include ActiveResource::Acts::Publishable::InstanceMethods
    end

    def publish(id, options = {})
    end
  end

  module InstanceMethods
    def is_published?
      (status == "published" || status == "edited")
    end                
  end            
end

ActiveResource::Base.send(:include, ActiveResource::Acts::Publishable)

Now here is what the model will look like:

class Article < ActiveResource::Base acts_as_publishable end

Now we can mix this functionality into any code base. If you have database fields that relate to publishing they can be mixed in via migrations when the plugin is installed.

I’ve come across a number of web applications recently that cross-link between other applications to steal their functionality.

This sucks!

It leads to poor application design as sooner or later developers come along and are naturally confused about what should go where. They then increase the amount of cross-stitching between the applications. Eventually you end up with one large application that’s not so great at doing two things. You have to get both applications working independently when you just want to use one. It wastes time and it creates a mess. The more applications you connect this way, the worse it becomes. It lowers the quality of both applications and kills code velocity.

Stop the madness!

For those of us that are Rails developers there is a pre-determined place to put outside dependent functionality - the ‘vendor’ path. If you put all of your external dependencies there you have a nice self-contained application that can stand on its own. Functionality shared between applications can be broken out into mutual dependencies and be pulled into the respective applications as plugins, frameworks, or gems that are stored in the vendor path.

If you have a framework, put it into “vendor/framework.” This is where rails goes for instance (vendor/rails).

If you have a plugin, put it into “vendor/plugins.” It’s the standard plugin location for Rails.

If you have a gem, install gemsonrails and put it into “vendor/gems.”

Now everything is nice and tidy. All you have to do to get your application ready for development or deployment is to check it out. No gem installations or framework installations. The dependencies are already met as soon as you get the code.



Seriously why do we still get these huge books on our doorstep every year? You know where mine goes now - straight to the dumpster. They don’t even make it inside. My phone can get all this information (and much more) on its own now. I can look up phone numbers, map, and get directions to everywhere I need to go.

So what exactly is the point of a “Phone” Book when the appliance it’s supposed to help us use can already do everything the book does and more?

Some people still collect these in the event Armageddon comes along and all of the sudden their computers and phones don’t work so they can’t get this information. Well.. news flash! if your phone doesn’t work then what the hell good is a phone book going to do you anyway!

I started phasing into a TDD workflow about year and a half ago. It took awhile to learn. Fixtures and test:unit were the tools of the time (so 2006). I didn’t see much about mocking, stubbing, or even factories until I started getting into Rspec about 5 months ago. TDD definitely improved the quality of my code but it slowed me down. I started programming with BASIC in 1984 after all (TI-99 ftw) so I have over twenty years worth of habits to overcome. Even now the amount of time I have spent doing functional programming dwarfs everything else.

Developers in particular must learn how to constantly adapt. Software Engineering has a long way to go and phase-gate/serial cycles aren’t the direction it needs to go in. Unfortunately there is a lot of resistance to changes in programming languages and methodologies. Most people cling to the old ways, the ways they were thought. A professor they respected told them to UML model every detail before starting to code so that’s what they do. Most people don’t want to constantly re-learn how to do their job. If they’re a developer then they need to find a new career path. We need to learn better ways of doing things and TDD is one of the most important improvements.

These days I’m doing 100% TDD and will never go back. I finally have the work flow down and not only has my code quality dramatically improved, so has velocity. My team is doing all TDD now and we burn through development at amazing speed. Our QA team almost never finds any defects because the developers are just as thorough during the TDD process. It took awhile to get to this point, but TDD doesn’t slow me down anymore - it helps catapult me ahead.

How many times have you received a hunk of completely untested code? Yeah I lost count too. I imagine your experiences were like mine, I bunch of mangled code that made little or no sense that really just needed to be tossed. Instead you have to black box it and put in a bunch of wrapper functionality. It’s legacy code. We’ve all experienced legacy code and it sucks. The really sad part is that we all wrote the same type of code that others are now wrestling with.

Untested code is legacy code. Everyone seems to assume that OLD code is legacy code. This isn’t true. C now isn’t much different from what C was 30 years ago. If code written in C a long time ago came with a complete testing suite, then all you would need to do is get it compiling and running. After that you can gradually make changes and rely on the tests to help lead the way. Inheriting Java code from 2 years ago is no different. If it doesn’t have tests, it’s almost certainly going to be legacy code. That means black boxes, wrappers and pain.

TDD ensures maintainability, provides documentation, helps in the design process, exposes architectural flaws early (you might think you’re an awesome coder but, trust me - you still have them) and (once you get it down) actually speeds up development. It also gives your code a life support system. Someone that comes along several years later should be able to pick up where you left off.

Give it a try and stick with it (if you haven’t already). It’s the only way to roll.

I always seem to be on the losing side of arguments that debate the finer points of the Universe. Sometimes the details are important but most of the time they’re just noise.

In these cases, I tend to follow the convention unless I have a strong reason not to. I don’t necessarily know how the convention came to be in all cases.

Unfortunately it’s surprisingly hard to convince others to do the same. Everyone likes to think they’re an expert. Expert is a subjective term though. As a developer, I picked the Ruby and Rails camps. I don’t necessarily blindly agree with everything that comes out of the mouths of Dave Thomas, Jim Weirich, and DHH, but I have learned to trust their judgment.

Finding mentors makes life easier. If you know you can trust the words of someone 90+% of the time, then you can build on what they know and not bother repeating the same arguments they have gone through. This is how “experts” work. Experts have a network of peers that they trust. That’s why they advance so much more quickly. They don’t bother repeating the details.

In order to become an expert you have to assume that you don’t already know everything.

I’ve encountered this situation once again. I’ve been following the RESTful Rails naming convention of using URIs where others use URLs. I did this because I trusted the judgment of the Rails Core team that this was the proper term. I always hated the interchangeability of the two so I was fine with just using one.

The debates came. There were inappropriate URIs strewn all over my code! These are supposed to be URLs I was told. I was asked WHY?! Why oh why have you strewn sloppy terminology all over our codes? My answer of that’s the Rails convention was not good enough. My peers wanted to replace all of these, I said “fine - if you really want to take the time on that.”

So… migrations are added, tests cases modified , source, documentation - all changed to reflect the “proper” naming scheme.

The truly ironic part. The initial naming scheme was right. That’s correct. All of that changed things to the WRONG terminology. It turns out that the Rails core team was right (imagine that). While it’s true that a URL must have an http, ftp, etc protocol at the beginning - it ALSO has to have an extension at the end that says how the resource should be presented. The concept is completely outdated now - which is why URL is considered obsolete terminology (just Google around for that).

I found the below… URI.. which describes the fine points of how the two differ.

http://ajaxian.com/archives/uri-vs-url-whats-the-difference

The lesson is to not assume you know more than everyone else. When a group of experts agree on something, maybe they’re right! Investigate the issue if you like, but don’t assume they’re wrong and you’re right.