Incremental refactoring

Saturday, June 1, 2013

Refactoring is an extremely important part of the process of developing software. It’s what makes your code maintainable with the help of it’s equally important counterpart test suite. It is always good to go on refactoring mode after you made your tests green, but what if you miss it? What if you let it slip and they you have this snowball that will, before you notice, turn into an avalanche? How do you recover from it without compromising your process and your velocity?

It is important to spend time making your code more maintainable, it will make your velocity more consistent in the long run, but sometimes you can’t stop all the feature work at once to fix all the design problems you have, sometimes it is just too much, you have to start iterating. To do that you have to first define your pain clearly so you can get an idea of what you want.

Finding the problem might be a straightforward task, it may be right in your face screaming to be solved. But often times your team aquires the stockolm syndrome and then no one can see the problem anymore, that’s when a new member to the team is most helpful, the untrained eye can see the unseeable. Sometimes you know the problem is there and you just avoid dealing with it because your current code is “good enough”. Well, it is probably not good enough.

The problem with code is that there is always another way to do it, and while you think your way is better, your colleague might think otherwise, and you can always think of another way and another way that will seem better that your current solution. That said, you have to try and figure out what do you want to solve, finding the problem doesn’t necessarily mean that you know how you ideally want to solve it.

We’re talking about large design problems that have grown overtime, not a single messed up object or method that you can just extract out in a single coding session. If you feel like it is something you’re able to extract out in a short amount of time I say just do it. But if you feel like it is something that would take at least a few sessions you have to think about what steps you’re gonna take.

As I said, code can be written in several ways, so can your steps be defined. Think about your goal and figure out what is the smallest part you can enhance towards it. Do it. You will not have solved your problem, you will be closer but not quite. For example imagine you have a big object that has turned out into a method bucket that doesn’t quite make sense anymore, let’s say you want to extract each of the methods into it’s own class, extract one at a time then, and let your method bucket slowly turn into a meaningful object or even better, vanish.

The end of this story is very rewarding, this strategy allows you to do a major overhaul in your codebase with the costs of it amortized over several pieces of feature work. Try it out.

Everything I know about Clojure after one week

Andrew Bruce

Saturday, May 25, 2013

This week I decided to clear out the cobwebs of my Ruby-trained brain and try a completely different language. Ruby and Rails have been my staples for over seven years, and I’m starting to tire of my patterns of thinking, and of the common problems found in large Rails applications. Specifically, I’m pretty bored of running into slow test suites and difficult-to-maintain apps. I suspect the primary cause of these problems is the entanglement of business logic with database and other stateful resource code. I get the feeling that it can’t be just coincidence that so many teams of competent developers fall into the same old traps.

I’d heard a bit about Clojure, so decided to explore the ecosystem and community. I’m attracted to the idea of learning a functional language, avoiding mutable state and re-evaluating the object oriented programming paradigm. Functional programmers are often accused of being “idealistic”, “academic” or a variety of other thinly-veiled primitive insults. If nothing else, I could learn to sympathise with these crackpot underdogs who claim to have the cure for most of the technical pain I suffer in my chosen occupation.

Hopefully this assortment of links and lessons learned will encourage you to try out the language, or inspire you to try something else that’s refreshingly new.

Clojure is easy to get started with

There are various tutorials online. However, they can be a little out of date. The quickest route to Clojure hacking is via leiningen, a sort of rake-meets-bundler utility. Assuming you’re on a Mac, have homebrew installed, a recent JDK and the usual code compilation dependencies:

brew install leiningen
lein repl

That’ll pull in Clojure for you. Once you’ve had a play in the REPL, use leiningen to generate an app:

lein new my-test-project

The project.clj that the above command generates is the equivalent of a gemspec, and declares the dependencies of your app. Leiningen helpfully fetches dependencies lazily when you start a repl, server or run tests. No bundle install step!

Homebrew can also install Clojure for you, but this version will be independent of leiningen apps. When you install it, you’ll be recommended to use a REPL wrapper for rlwrap. I’ve found that the one from the wikibooks site works better (i.e. at all).

Rich Hickey is an entertaining figurehead

Rich Hickey, creator of Clojure and designer of Datomic, the FP-friendly database system everyone’s talking about, has some inspiring talks from the end of last year about Clojure and Datomic, and notably why everybody is doing programming wrong. There are some pretty strong views in the talks, but they’re a refreshing take on the sociological patterns in our industry, and how project pathologies can be treated.

There’s an active community

Many clojure developers are ex- or current-Rubyists. For example, Jay Fields maintains the expectations testing library (more on this below).

Clojure has artsy cred, too: there are several videos on the web showing Clojure being used for live music.

Syntax change requires healthy brain re-wiring and thought simplification

After spending so much time wrapping my head around object-oriented constructs and trying to work out how best to structure OO programs, it’s a refreshing change to work with a functional language. Not having a CS degree, I’d previously tinkered with Scheme following a workbook. I wasn’t put off by parentheses, but did have some fears that I’d be transported back to the bad old days of the top-level PHP namespace. I soon realised, however, that my beef with PHP was mainly the aforementioned comingling of state and logic, as well as the inconsistencies of method signatures and names.

Clojure philosophy is all about consistency and reuse. I’ve trained myself to believe that reuse is all about identifying concepts, naming them and adding an abstraction, often a named value object. I’m pretty attached to my explicitly named classes of values, like SubscriptionEvent or PersonName. This is largely in reaction to the recognisable OO smells like Primitive Obsession. The problems inherent in such smells generally melt away in the FP world, since you’re encouraged to use the built-in types to provide equality and the like, and to use the common functions like map, reduce and so forth to achieve what you would do in OO with a value object’s methods.

Web development is potentially full-stack

This is worth knowing if you don’t already: Clojure already compiles to JavaScript in the browser, as well as to Java on the server. So we potentially could be doing single-language full-stack development like node.js but without the oft-cited pitfalls of JavaScript. An excellent resource for newcomers to Clojure is this translation between JS and Clojure.

I’ve begun a project for playing around with the Compojure web routing library. Compojure forms the basis of many Clojure web apps, and I’m using that repository as a place to stick my learnings. I’m test-driving each new feature, so that it might serve as a reference for other newcomers on how to do TDD for Clojure web apps.

TDD is easy, fast and totally not banned.

Watching the Hickey talks, you might come away with the impression that the Clojure community is anti-TDD. However, there are some excellent developments going on in this area, such as the aforementioned Jay Fields’ expectations library, which provides an achingly simple way to express intent in tests. See my first attempts at testing a web app for an example of this. Structural whitespace optional.

Monads still a mystery

One week just wasn’t enough. See if you can figure it out and send me a postcard with a succinct summary.

Until next time!

Designing an API in Hell

Andrew Bruce

Sunday, May 19, 2013

Minitest, Ruby’s built-in testing library, has some great out-of-the-box features. One of these is test parallelization. Parallel testing is often added after a suite gets slow enough to hurt. That can be achieved using the parallel_tests gem, which takes advantage of today’s multi-core processors, or using custom solutions for dividing chunks of a suite across several machines. Arguably, test speed should be dealt with by making code design changes, but that’s another story: what interests me most about minitest’s parallelization is the constraints it places upon the design of stateful systems when TDDing from scratch.

You can turn on parallelization for a particular test case:

describe Server do
  parallelize_me!
end

or for all tests:

require 'minitest/hell'

As the name implies, the latter approach turns up the test pain level to 11, but it’s the kind of pain that can have positive effects. For ‘fun’, I started to use minitest’s parallelization on a side project, which has a stateful API backed by a relational database. Here are some of the decisions that were forced out by using parallel test examples.

Commitment to fast tests

I thought that running tests in parallel from the start of a project would make me lazy, causing me to neglect slow tests because they’d be running at the same time as others. Surprisingly, the opposite happened: the need to constantly rerun the whole suite to iron out nondeterministic conflicts encouraged me to fix slow tests early. I ended up being able to run the entire suite several times within a matter of seconds in order to check the tests’ ability to run in parallel.

Side note: this is an early-stage project, with a very low quantity of tests! It will be interesting to see how test speed increases as the volume of tests increases.

Avoiding test duplication

Since the unique constraints of my database could be hit by tests with the same fixture data running at the same time, I was encouraged to use more intention revealing test data for each example, avoiding foo and bar, which commonly litter a suite and make tests harder to read.

For IDs, I used Ruby’s SecureRandom library, which provides GUID and hex generation. I sometimes used hex generation when the user-supplied unique display name of something didn’t matter to the test.

Client-side ID generation

Although not strictly forced out from parallel tests, parallel testing got me thinking about how best to interact with the backend, which has a single database being served by multiple concurrent requests (just like any web server).

Using GUIDs instead of autoincrementing IDs can be a smart decision to make if you can (i.e. you don’t need human-friendly URLs), because it means your database server doesn’t need to worry as much about ensuring uniqueness, since the GUID algorithm effectively guarantees it.

TDDing my API from scratch, without external requirements, encouraged me to use GUIDs to simplify the design and to avoid bottlenecks at the database layer. POST requests canonically return the new URL of the resource you’re creating in the Location header of the response. So to test that a thing really got persisted I’d need to:

POST to /items with a representation of the resource
Grab the Location header of the response to get the new URL
GET /items/:newid and ensure the response body matched the representation I sent

This seemed a very laborious process for storing some data. Much less work is:

PUT to /items/:newid
GET /items/:newid and ensure the response body matched the representation I sent

Since GUIDs can be treated as unique, it didn’t make much sense for the server to generate them.

Positive effect: the app would now cope with a distributed database system on the back-end, despite starting out on a technology that’s thought of as difficult to scale horizontally (SQLite).

Avoiding database resets

It’s common practice to wipe the whole database when starting a new example, or to run each example in a transaction and roll it back when each example finishes. I wanted real black-box tests, so I didn’t want to use transactions. Yet, deleting the whole database at the start of an example didn’t play nice with minitest’s parallelization, since data that one example required would be deleted by another.

The usual approach when using parallel_tests is to create a database for each process. However, since minitest doesn’t manage databases (nor should it) I chose to keep a single database and find a different solution.

I chose to sandbox all of the tests by creating new entities each time, and only checking for output that indicated that particular entity had been worked on. The product I’m working on is a Continuous Integration server, so I’d be creating CI projects (you might also know them as jobs) and expecting them to appear in an XML feed. The tests had to be OK with other data being present, since the other tests could be working too.

This approach precluded tests that checked that the number of records had increased by one, because in an otherwise acceptable “green” test situation they’d occasionally increase by more than one (another test added a record too), stay the same (another test deleted a record) or decrease (more than one had been deleted).

Constraints are fun

While I wouldn’t recommend going rogue like this on a client project, playing with constraints like truly parallel tests can get you thinking about your normal testing procedure. Some of the above decisions allowed for a much faster test execution time, and always having the assumption that other processes could be working on the database forced out some interesting techniques. Some of the techniques I had to avoid due to parallelization would normally necessitate different workarounds with their own drawbacks. For example, if you always assume the count of an ActiveRecord class will go up, you require exclusive use of the database. If instead you scope your queries to a parent entity, this restriction would be removed.

Hell isn’t so bad after all.

Smelling with your ears: TDD techniques to influence your design

Andrew Bruce

Sunday, May 12, 2013

Test Driven Development can be a hard sell. The first pitch is often designed to entice the buyer with safety features, like:

“How will you ensure that those bugs don’t creep back in?”
“Wouldn’t it be nice to know that one change doesn’t break another?”

In conversations between practiced test drivers, though, design topics tend to pop up:

“What is this test telling us about the design of our code?”
“Why is this test boring to write?”
“Why is this test so slow?”

Then there are really exciting questions, when getting close to a design breakthrough, like:

“Is this test telling us we’re lacking polymorphism in our design?”
“I’m tired of constructing this thing. How can we group this set of arguments into an object with a name?”

One distinguishing factor between these types of questions is the level of trust in TDD. Someone with little trust might be predisposed to abandon testing before implementation, instead choosing to test afterwards, or not at all. To such a person yet to be sold on the benefits of TDD, the safety questions make more immediate sense, while design questions are often met with blank stares. However, the safety concerns are easily brushed off: it’s a prototype. My team is so smart we don’t need tests. We need to move fast, so we’ll worry about tests later.

Explaining the basic advantages of TDD doesn’t always work as a sales pitch, because those explanations don’t reveal why testing can be difficult, much less why testing sometimes ought to be difficult. Take someone who has never let the design of their code be influenced by tests: they dislike testing for being difficult or boring. Encountering resistance in the TDD process, they choose to forgo the safety advantages of testing, and the design advantages haven’t been made clear.

As you may have gathered, I’m more excited by the design aspect of TDD and related tools than by the safety aspect. I’d like to think that if we sold how TDD can improve the design of code that’s yet to be written, we’d have an easier time tricking our friends into writing code with regression protection.

Learning to listen

There is much talk about “listening to the tests” among TDD practitioners. The listening analogy is apt. Like listening with our ears, the ability to understand what a test tells us about code quality can improve with practice. It’s a subtle concept to grasp, and one I frequently find is not well understood by otherwise experienced developers. This is unfortunate, because it’s a crucial part of getting rapid feedback on the quality of production code. By quality, I’m referring primarily to the ability to cope with changing requirements, as opposed to good coverage of features and edge-cases.

If you can’t hear what your tests are trying to say, there are tools for cranking up the volume. Below are a couple of my favorites. They’re not intended as hard-and-fast rules, but as exercises to try out when you’re frustrated with a test or wondering why it’s getting difficult to test something.

If you haven’t already, you should read about known test smells and their solutions, because we can apparently smell with our TDD ears.

Use your testing framework’s convenience helpers sparingly

In the RSpec world, this often comes down to writing readable examples without using ‘subject’, ‘let’ or ‘before’. It turns out that straightforward assignment is usually OK.

As this Thoughtbot post argues, the let helper effectively introduces Mystery Guests (implicit, hidden fixtures), and overuse results in slow and fragile tests.

I like to avoid lets, subjects and other test helpers for another reason: if I can’t stand to repeat myself in examples, I think about how the code that uses my code will feel. A boring, repetitive test setup might be telling me that my code has too many dependencies. If I’m frantically stuffing things into the database and stubbing out web service requests just to allow myself to construct an object, perhaps the object’s scope is too broad.

If you come across a test that is apparently repetitive, consider tidying the implementation of the system under test before the test itself. You may find that the noise in the test can be dramatically reduced with some production code tweaks.

Avoid stubbing methods to return values

I owe this one to Greg Moeck, who introduced something like it at the San Francisco eXtreme Tuesday Club.

First, a reminder of the definition of stubs versus mocks (to paraphrase Gerard Meszaros):

A stub is a test double that allows you to control the indirect inputs of the system under test.
A mock is a test double that allows you to test the indirect outputs of the system under test.

If you return a value from a stubbed method, you force your production code to depend on a blocking, synchronous call. If you could otherwise send a message and not expect an immediate response, you permit your design to (now or in the future) be asynchronous.

Further to that, if you instead use a mock to expect an output to the collaborator you were previously stubbing, you can more cleanly divide your testing into inputs and outputs of the system under test. It’s the difference between:

it "ensures user is authentic before performing the action" do
  user = stub('user')
  authenticator = stub('authenticator')
  authenticator.stub(:authentic_user?).with(user) { true }
  action = Action.new(user)
  action.perform
  expect(action).to be_complete
end

and:

it "ensures the user is authentic when action is requested" do
  user = stub('user')
  authenticator = mock('authenticator') # assume the player of this role knows who to tell when authentication succeeds or fails
  authenticator.should_receive(:authenticate_user).with(user)
  action = Action.new(user)
  action.perform
end

it "performs an action once a user has been authenticated" do
  action = Action.new(stub('unauthenticated user'))
  authenticated_user = stub('user')
  action.user_successfully_authenticated(user)
  expect(action).to be_complete
end

The code that passes the second set of examples is in better shape for when you need to queue requests to the authenticator and complete the action asynchronously. It uses a “tell, don’t ask” style. The fact that an explicit message is sent to the system under test (‘user_successfully_authenticated’) makes it clear to the reader that the request for authentication and the triggering of the action are separate bits of work. It’s someone else’s business whether I get told about the successful authentication, and how many steps are taken before I’m told.

There are several more techniques I’d like to tell you about, but this post is getting a bit long in the tooth. Maybe next time. Happy listening!

Winning a Rumble

Luan Santos

Saturday, May 11, 2013

Last year before I joined Pivotal Labs me and my friend Raphael Costa participated in a brazilian Rumble, inspired by Rails Rumble ran by the folks from Startup DEV. It was a very interesting experience and I learned a lot from it. We won first prize, and I want to tell how we did that, and why I would change some things if it was a real project supposed to live more than 48 hours.

First, if you don’t know what a rumble is, a rumble is a developer’s competition where you have a very limited time to develop an app, your result is evaluated by some folks and the best app (according to their criteria) wins. In the case of Rails Rumble or Startup DEV rumble we had 48 hours over a weekend.

The plan

The plan can and should be draw before you start the rumble. When the clock starts ticking you have to laser focus in implementing everything you can.

First thing you need is an idea, it doesn’t need to be revolutionary it just needs to be implementable and easy. If it’s revolutionary, bonus points for you. Once you have an idea you have to describe in detail what is the featureset you are looking for.

When you have you featureset, you have to remove everything, EVERYTHING that is not absolutely required for your MVP, sort the features you removed in nice-to-have order in case you have spare time at the end.

Draw your mockups on paper and have them ready and attached to each story you selected as part of your MVP, if you have a designer, great, make him draw more detailed wireframes, if you don’t then you’ll have to use the tools the world provide you, such as bootstrap or foundation or whatever you prefer, do not waste time in things you are not expert in.

Split tasks based on capacity, in our team we were two developers, I had more experience with dev-ops (and we had to deploy our app to a VPS that was provided by the organization) he had more experience with UI/UX design, so I barely thought about how the app should look, and he barely used ssh.

Applying the plan

The basic procedure is: pick a story, assign it to you, implement it as quick and simple as you can, deliver it asap, move on.

Stay in sync, you have to know what’s happening with the other folks in your team, if your team is larger than 2, it gets more and more dangerous. You do not want to spend time resolving complicated merge conflicts so make sure the tasks are well parallelizable and that no one is stepping in no one’s toes. We had quick check-in (2 minutes, standup style) every 2 hours.

We knew what we were capable of, so we didn’t try to do anything other than that. If you never implemented a payment gateway, don’t try to do so in a 48 hour project, you will waste time and you won’t be able to finish. We knew how to TDD and we had paired before, but these were things that we were not used to do, processes not clear in our minds, we would have to learn it on the go and we would fail if we tried. When you try something new you will certainly spend time figuring things out. So because of that we didn’t even try, we did not test, we did not pair.

Commit often, commit every time, on every change. This avoids complicated merge conflicts and saves you a lot of times. Write decent SHORT commit messages so you team can understand what is that that you did just by parsing the message quickly. Pull often, see the log, git log --graph --oneline was the command we used to quickly parse messages, alias it to something simple, like gl, for example. Once you finish a feature, deploy it. Make sure everything works properly in your deployed environment.

We finished everything and more with about 2 hours to spare, in this 2 hours we looked for bugs, found some and fixed them. This spare time is essential specially if you are not TDDing, you will find problems.

What would I do differently

First of all, if you want your app to continue after the 48 hours you have to TDD, on the next day after the competition we looked at the code and it was only OK, it wasn’t bad or anything, but it was very hard to trust it and make changes because without any tests you have no confidence on doing it. The solution for us would be rewrite the app TDDing or backfill, and backfilling is very painful.

Skiping the tests is very risky, you may break everything without knowing, and that would make you fail, we took that risk and it worked for us. I wouldn’t do that again, I would TDD next time even if that means reducing the scope even more, it’s too hard to develop a real app without it.

Pair programming and TDD are things that make you very productive on the longer run, on a 48 hour crazy competition it might not be the best thing to do if you’re there to win and your team is only composed of two people. If you have a really small and simple featureset and your team has experience you can get away without it and it would be faster on this 48 hour streak. It is very likely that you will have to rewrite your app after tho.

I would pair if I had a team of 4, a single pair may not be the best for a 48 hour thing, you kinda need the parallelism on this short project. The ideal setup would be two pairs tho. More than 2 parallel developer stations would probably be a bad thing.

In conclusion

Participating is fun, we had a lot of fun, there were several good projects on the competition and it was awesome. If you ever have the opportunity to participate in one of these you should, it’s very tiring but it is worth it at least once. If you’re interested our project is still online at agrupe.se (it’s in portuguese, sorry, google translate).

Vipe, a Vim command pipe

Luan Santos

Friday, May 3, 2013

When I’m doing outside-in TDD (and that is basically whenever I’m coding) I often process things as a stack. I write an acceptance level test, run it. It fails (hopefully), so I write a lower level test, let’s say, a controller test. It fails. I might need go further and write a model unit test.

When I finish the inner TDD loop (say, unit on a model) I want to “pop the stack” and run the controller one, having that done, I want to run the acceptance test again. Often times the inner part of the loop takes long enough that you might forget what exactly what you were doing before, lose track of the files you had and ask your pair “what was the feature again?”.

This is a general problem and I think every editor can have a tool to solve this. I couldn’t find it for the editors I use on a daily basis (Vim, Sublime Text or RubyMine, depending on who I’m pairing with). So I got something that we use here at Pivotal and implemented my solution on top of it for Vim.

The solution we have here was created to solve yet another problem, how to run tests from Vim asynchronously, that means, without blocking your editor. Most development environments have this functionality and I think it’s quite useful specially when pairing.

There are several ways to accomplish it in Vim, and we have been doing this using a unix pipe thanks to my coworker and good friend, Andrew Bruce.

The reason why I like this setup very much for pairing is because it raises the visibility of the test results, I like them always on screen so both can see it all the time regardless of how fast you can visually parse it, it looks somewhat like this:

Screen Shot 2013-05-02 at 1.17.12 PM

So you have you code in a window and your test results always visible. As a bonus, if you are on OS X and using iTerm2 you can ⌘ + Click a filename:line number to open the file in MacVim (Preferences -> Profiles -> Advanced, Open With Editor…, MacVim).

This is all very good and helps a lot. But I wanted a bit more, the first thing I noticed is that I kept wanting to run arbitrary commands that our “test_server” don’t support.

My fork of Andrew’s idea, vipe, is a more generic command pipe, that runs anything. With that I am able to send commands to the terminal and maybe map a key to it. For example :nmap ,t :Vipe ruby <c-r>%<cr> for simply running a ruby script with ,t. To do that I removed all the ruby/rspec/rails specific functionality from the original version and moved that into my personal vim config.

And then I implemented my most wanted stack of commands in Vipe. Running a command will automatically push it into the stack, you can simply run :VipePop and it will run the previous command, as simple as that. Similarly :VipeRerun reruns the last command.

And that’s about it, Vipe is a command runner for vim that has a command stack and allow you to run any arbitrary command you want, I haven’t spend so much time perfecting and I think there is space for improvement. I hope you find it useful.

Fighting test pollution with an RSpec custom ordering strategy

Andrew Bruce

Thursday, April 25, 2013

Test pollution manifests itself as seemingly false negatives or false positives in a test suite. It occurs when some shared state is unintentionally modified, or unintentionally read and used in a test.

When test pollution builds up, it can mean that a project’s build fails unpredictably, which can stop a whole team from shipping code regularly. This is an expensive way to not build software.
Continue reading →

Executable Documentation

Will Read

Sunday, June 3, 2012

I try to avoid writing static documentation. It gets old and out of date as soon as the next person comes along because it is logically far away from the code it describes, so event the best intended developers won’t always be aware of the documentation dependencies. Since working at Pivotal I’ve enjoyed writing tests first with RSpec, which results in one form of executable documentation to describe behavior to other developers working in the code base. But what about when you need to express behavior to people outside of your code base? Maybe your stakeholders have a company requirement of documentation, maybe you’re trying to entice third party developers to use your new HTTP API, or maybe you just want people to install your gem, what then? Your audience matters, and there’s a variety of tools out there to use depending on your needs.

Human Readable

Cucumber is one tool that can be used to fill this need. It’s designed to be a DSL for creating DSLs to describe your application. It has a nice attribute that it is very human readable. You can then use tools like Relish to publish docs from your Cucumber suite. The drawback is that you put a lot of effort in to expressing what you want in English, which is great if you’re really showing this to non-technical people, but it can be an over optimization if your readers have some technical context.

Dev Readable

In the case where your audience is an outside developer, something like rspec_api_documentation might be more appropriate. It layers on a DSL to your familiar RSpec DSL that lends itself to HTTP APIs. This is great because your RSpec tests become more expressive without the overhead of defining the DSL yourself. From there, you run a rake task to generate HTML. Your spec runs will fail if your docs get out of sync, which should be never if you have CI. The web is an easy venue to consume this kind of information, but the tool doesn’t let you editorialize much beyond the description of the resource and the parameters.

The Best of Both Worlds

One of our open source projects here at Pivotal Labs is Jasmine, a JavaScript testing framework that runs in the browser. Unlike Rspec where you need to have ruby installed and a database set up and so on, everyone has a browser. Check out the jasmine docs and scroll to the bottom. That’s right, the examples are tests, the comments are close to the tests so when the test fails you know to update the text as well, and now someone has a working example of how to use Jasmine all in one. The page itself is generated using Rocco, a Ruby port of Docco.With the combination of docs generated from tests, and tests that run in the browser you get this perfect blend of readable, easy to maintain documentation that is available to your entire audience.

Sometimes you have to provide documentation, but that doesn’t mean it has to be outdated. By creating executable documentation you can have confidence that the code and docs are staying in sync. Consider your audience carefully when choosing how you will document your software and know that there are more than a handful of options available, one of which will probably suit your task well.

Testing mass assignment with RSpec-Shoulda

Mark Rushakoff

Monday, May 28, 2012

If you’re new to Rails, or if you’ve been using Rails 2 for a long time, you might not be aware that Shoulda offers an allow_mass_assignment_of matcher that works just like it sounds. Here’s the example from the source code:

it { should_not allow_mass_assignment_of(:password) }
it { should allow_mass_assignment_of(:first_name) }

Having explicit tests for whether fields should be mass-assignable is probably safer than letting developers arbitrarily add or remove fields from the attr_accessible declarations — at least when they break a test they’ll have to think twice about it.

Pivotal: Why It Works

Will Read

Thursday, April 26, 2012

My name is Will, I’m 30 years old, and I’m a Pivot. In my three year tenure here at Pivotal Labs, I’ve found that it may be easy to see the parts that make us successful consultants, but that forrest is hard to see for all the trees. Everything from breakfast to keybindings plays a part in making us one of the top software consultancies and the greatest place I have ever worked.

My story starts with breakfast and ends with trust. Each piece plays in to another, and the result is an environment where teams are autonomous, culture and knowledge spread quickly and organically, and communication is never a secondary priority. Our clients see the results in the way which we interact with them to deliver exactly what they need. My coworkers feel it when they realize they control their own destiny and have all the power to make their situation better. You hear it when you listen to pivots like myself or others who appear at conferences across the globe. What we have here is special.

Breakfast – The Most Important Meal of the Day

We have breakfast prepared for us by an outstanding catering staff. It is delicious and you should be jealous if only because it means that there’s one less thing I have to do in the morning. It isn’t just food though, and it isn’t a ploy to eek out more hours from pivots like other companies that might provide dinner in hopes that you don’t leave till midnight. No, breakfast is much deeper than eggs and bacon – it’s a time to cross pollinate, to talk to the pivots who aren’t on your team to share in things both work and non-work related. It also gets us to the office at the same time, which makes it easy to pair together for eight hours, then we all go home together at six, and breakfast leads us right in to our all company standup.

Standup – You’re Not Alone

Yes, the whole body of developers participate in the biggest, most high value standup you’ve ever seen. At pivotal you’re never alone, and company standup is just one of the ways we assure that is always true. When you have hired the best (more on that later), why wouldn’t you want them all to be on every team all the time? Since mitosis of humans hasn’t left science fiction yet, we have to settle for osmosis. We go over who is new or visiting the office, who needs help, and what interesting stuff has come up that might be relevant to other teams. You can read our standup notes right here at pivotallabs.com/blabs. Culture starts here too. Company jokes develop over time as we all gripe about the bumpy release process a particular tool is going through. Company standup also makes it clear that it is okay to not know things. Let me say that again: It is okay to not know something.

Another pivot, Davis Frank, shared an analogy that resonated, but since my Bruce Lee knowledge leaves most wanting, I have adapted it to a much geekier Star Trek take. Being a pivot is akin to being a senior officer on the bridge of the Enterprise. We hire people who will speak up and collaborate, people who will work to make exploration sustainable. We all come to Pivotal Labs with our own expertise like Jordi with his engineering skills, and Beverly the medical doctor, but the very nature of working with startups and our other clients means that we are always going “where no one has gone before” with respect to code, and sometimes the ship’s councilor has to hot wire a tricorder. There is no manual on how to build Twitter or Groupon. Pivotal never gave me the answers to those problems, that’s not how we work. Instead, Pivotal, like Star Fleet, exposed me to a lot of problems all the time and gave me the resources and teams to help me solve them as I encountered them.

Pair Programming – The Trust Builder You’re Already Doing

After company standup and our own team standup, we pair program. That means two people, one computer, all day. It isn’t half as radical as it may seem at first glance. Has anyone at your standups ever asked for help? Did someone then go over and sit with that person at one computer? I suspect they did. Do you do code reviews? Then aren’t you really asking your team to share coding knowledge and culture? Think about it. This is what pairing is all about, we’re just set up to do it a lot more often. And getting back to trust, pairing turns a potentially threatening code review process in to a co-ownership process.

Pairing builds trust in all directions. It builds trust between the pair and the client accepting the user stories because I know that two people have thought about this problem. I also know that any cultural nuances that one pivot has picked up are being shared inline with the other pivot. Pairing builds trust between devs. If you talk about code with someone for eight hours a day you can’t help but understand how he approaches problems. That said, you may not always agree, but at least you understand, and you can have much deeper, more meaningful collaborations when that understanding is in place. Pairing develops trust between the team and the individual because I know that if a feature fails, I am not alone in the failure, and if the feature succeeds, I will have good company to celebrate the success.

Talking about code for an entire work day is hard, I won’t pull any punches there. Think about the last time you were in a long white boarding session. I might have been needed, and possibly energizing, but I bet you also needed to decompress for at least fifteen minutes after. Pairing is like that, so we find other ways to communicate that also happen to feed in to the trust: Test Driving. Write tests first; that way, as your pair, I know what we’re about to work on for the next five to twenty minutes. Writing tests first is a great way to enhance your pair’s understanding of how you’re thinking about a problem and the potential solution. Once you have the test, it has the added benefit of speaking to future devs who might work on this code and communicate what it was meant to do so they can make an informed decision whether you’re available or not. Speaking of which, since we rotate between projects, someone not being there is more than just a possibility, it’s just a matter of time.

Rotate your Pivots Every Six Months or 10,000 Spec Runs

The average pivot is on a project for 3-6 months, some stay longer, some are shorter if their leadership is needed elsewhere, but in general you can count on seeing a good number of projects in three years’ time. On one project you might make a JSON API, and on the next you’re up to your eyeballs in JavaScript, HAML, and CSS. Then it might be off to help a company scale and tune performance. We swap people around and expect them to be adding value on a new project day one. We do that by standardizing on a few things about our workstations. For starters, every computer is basically the same minus the project code itself. Our ops team has done a great job of having an updatable workstation image that is under test so they know when it breaks. After many holy wars, we’ve also come to an arrangement about which IDE and keybindings to use. The choices may not always be “the best” when getting down to specifics, but it is one less hurdle to jump when you find yourself on a new project with new faces, new clients, and new domain – at least your computer feels like the home you just left. It also means I don’t have to think about how to set up a machine when starting a new project, the collective knowledge of Pivotal workstation config is captured in our machine image.

Rotation is a razor sharp double edged sword. Your average dev working for a product company might switch teams once in three years. Meanwhile at Pivotal Labs, I’m seeing new problems and new solutions at a rate 3-6 times that. It means that I can demonstrate loyalty by staying at one company, but the experience of working for ten companies in that same timeframe. Rotation makes our best pivots that much better. The downside of course is that someone who demonstrates loyalty but possesses the experience that is characteristic of a senior pivot soon finds himself being invited to take on lucrative and dazzling roles elsewhere. I can’t begin to explain the sadness and frustration I feel when a pivot leaves the company, but we also can’t afford not to train up our employees. It is the same high quality that makes pivots hirable that brings in the steady stream of clients to Pivotal Labs. If we stunted or slowed that growth any way, it would weaken our offering in a way that would undermine much of what is good about Pivotal Labs.

Hire the Best

We are unwavering when it comes to hiring. When you come in for an interview, you write code on real product because that’s what we’re expecting you to do when you’re here everyday, not solve brain teasers at some white board. We want to know if you can communicate, and we want to know if you can learn and adapt. Pivotal throws pivots in to uncharted waters a lot and we expect pivots to swim. They always do because we hire great swimmers. Hiring great people means we don’t have to spend a lot of time with formal training, or managing, because people are good citizens within the company. Also, hiring great people who raise the average and are put in a place where they pair and rotate means that the average really does go up for everyone. This has an awesome effect on morale, and serves to give us all the confidence that we need to takle new problems. Having the best means that teams can be autonomous and we can trust them to interact directly with the client eight hours a day. We don’t have any need for the “heros” or the “ninjas” who can strap on headphones and have a caffeine-induced flow session. We hire largely for technical aptitude and ability to communicate which is not most developers. When you’ve hired the best for this business, delivering features comes naturally.

Focusing Priorities with Pivotal Tracker

The real magic of Pivotal Labs that you might not notice at first is Pivotal Tracker. It may look like an ordinary project tracking system, but it does two things very well that most software fails to do: 1) Tracker forces clients to prioritize the work we do for them, and 2) it serves as a central communication piece. The former is very important to the success of the project. I’d like to think that because of all the other things we do, we produce more features period, but that’s not the whole picture. Because everything is prioritized, we produce the right features, or at least the features the client wants the most. It is hard for a client to be dissatisfied when we’re always working on the most important thing. We know it is the most important thing because we’ve talked about it. Tracker is the main talking point in our short, weekly meeting so we know that our client wants these features first, we talk about any technical needs we have on our side, and discuss the story details beyond what is typed in Tracker. Remember how I said it all plays in together? Well since we all sit together, and we all trust each other, it greatly reduces the need to spec out every last detail – most of the time we have enough context to make well informed decisions, or we can turn around and ask our client for clarification, or baring that we deliver a story and get some great feedback in the form of a rejected story. At Pivotal, you’d have to work really hard to not deliver what the customer wanted.

Feedback – Always, Everywhere

Being an Agile shop means we’re always gathering feedback and looking for ways to do our job better. Each project is different, so we have regular retrospectives to help us surface and adapt to those differences. This exercise is focused on getting better, and depends on honesty and therefore builds trust in a team. This goes hand-in-hand with hiring the best, because the best speak up and the best aren’t afraid to say something scary or controversial. The best lay their ego aside in order to improve a team, project, or a company. I strongly believe that, if left alone, the right people with retrospectives would arrive at a process that looks a lot like Pivotal Labs does today – in fact I would argue that’s what happened when the idea of Agile was first put to paper by Beck, Fowler and the rest of the Agile work group. Get and give feedback, act on that feedback, that’s the core. Action however, doesn’t always lead to success at first try.

If at First…

In fact, taking action leads to failure a bunch. Since the set of problems, both human and technical is huge and enormously complicated, it is reasonable to assume that most guesses at actions would end in failure. But guess what, we fail, get feedback, take action, and over time, those actions lead to successful actions. Often times the success is very different than it was originally pictured. We also have the benefit of having that experience that can now be applied to a future project. Pivotal Labs is good about making it safe to fail. Read that again, it is safe to fail here. Why? Because we start with the best, then we give them a lot of experience, and we trust them to make the best decision given the information and experience they have. And because we’ve hired for it, teams own their failures, and they’re intrinsically motivated to do better. No one has to sit over their shoulder and tell them it went wrong. They know, and as a matter of pride they’ll fix it. Most importantly, they have the skill set and the resources to fix it.

Greater Than the Sum of its Parts

By now you should be hearing it in your head, that it all feeds in to itself. The whole thing works because it is complete. Each part, start time, pairing, test driving, hiring, clear priorities, and feedback contribute more to the system than just its stand-alone value. The pieces are all obvious, but how they interrelate and build trust across the organization is what makes Pivotal an outstanding company. My name is Will, and this is why I’m a pivot.

If you’re looking for developers, and you want to get the most important things done, I hope you’ll consider becoming one of our clients, we do web and mobile work and you can drop us a line at sales@pivotallabs.com. If this resonated with you and you’re looking for a job as a developer, please send your resume to pivotallabs.com/jobs.