Write README as the spec for the tool.

Tom Preston-Werner has helped bring RDD (README Driven Development) some
much needed attention. This is by no means a new concept. Writing down
your current understanding, of the tool / problem at hand, is a good way
to help flush out the ideas in your head.

Here we have a relatively simple tool and are updating our README to
reflect this knowledge. We are adding code samples to demonstrate to
users how to install and use the tool.

What we write here will help to serve how we start the BDD process.

See also:

  * http://tom.preston-werner.com/2010/08/23/readme-driven-development.html
  * http://www.slideshare.net/maetl/readme-driven-development-12783652
  * http://programmers.stackexchange.com/q/205706
Start with a high level feature specification.

With BDD, focus is generally on a top-down approach. It also focuses on
how end-users interact with the program. It is not concerned necessarily
with implementation details.

Using this approach, the feature specs are based around user / job
stories. They view the program as more of a black box. Due to this, most
tests tend to be full integration tests where no mocks or stubs are
used. Instead, the focus is solely on environment state changes.

Since some features can a involved and require lots of new code, they
are generally marked as `wip` for "work in progress". This allows the
incomplete feature to be excluded from the main test run, while it is
implemented.
Add executable for the cli.

Here we add the `adder` executable for the CLI. We setup the shebang to
run the available version of Ruby. We also set the executable bit on it.

Print the usage when the executable is run. We can run this locally by
executing "bin/adder". The `spec_helper` already adjusts our path for us
so that we can omit the `bin/` path in tests. Once the gem is installed
we can let bundler handle adding the `bin/` path for us.

Lastly, the wip tag is removed on the spec as it is fully passing.
Add the next job story.

Following a stricter TDD approach, we add a test for what happens when
only a single number is provided to the adder. Once again, as this is a
feature spec, we mark it with `wip` until the feature is complete.
Write the desired implementation of the feature.

This is our chance to write the code we wish we had. It doesn't matter
if none of it exists. We will create it. This is our chance to define
our internal API for what objects we have, how we interface with them,
and what they return to us.

Our existing spec still passes; though the wip one fails. This is fine.
We expect the wip specs to fail on some commits, that's why we marked
them. Since our existing spec is passing we can safely commit this
partial feature implementation with out worrying that the existing app
is broken. We'll continue to follow this process as we build out the
features.
Add missing class and methods.

We add just enough code to make the feature spec finish. It is still
failing, but it is no longer raising exceptions related to missing
classes and methods.

At this point, the feature spec is waiting for the lower level classes
to be properly implement. It will need to stay as `wip` until we finish
this.

We need to now drop into more unit level tests in order to continue the
program.
Add failing sum unit test.

Once again it's time to write the failing test first. This type of test
is a unit test. It's only testing a single object. The goals with unit
tests is, given various states, verify behavior of a single object.

We've also, once again, marked the test as a `wip` as it's failing; and
we don't want to break the build. In a normal system, this commit will
most likely not exist. Instead it will be committed along with the
passing behavior having been implemented. It is being committed
standalone to clearly delineate that we are writing the failing unit
test first.

Future commits may merge the behaviors together and only note in the
commit that the test was written first.
Implement the adding machine sum behavior.

Many people do not write comments in Ruby, myself included. However, in
this case, I felt it necessary to help spell out the full spec of the
method as we defined it (in our heads and explanatory comments) in the
executable.

While the test only passes in a single number, we've written the method
definition to support multiple numbers. It would be more work to just
strip off the first number and adjust it, than it was to write the
implementation that we did. Again, "strict TDD" would dictate that we
write something like:

   BigDecimal.new(numbers.first)

As with most things, there are shades of gray to the processes. In my
experience, to date, there are little added benefits from these tiny
steps for simple methods. For more complex ones, or others where the
algorithm is not readily apparent, I very much follow the stricter TDD
style to help flush out the algorithm that is needed.

Since the test is now passing we've removed the `wip` tag.
Flush out remaining parts of summing algorithm.

You may have noticed that our integration test is now passing. However,
it's still marked as `wip`. The reason for this is, I'm avoiding the
full BDD cycle. For me, I have the full spec of the
`Adder::Machine#sum` already. I dislike popping up the BDD stack when I
haven't fully implemented the known spec for the behavior under test.

As we go through and test things, I want those tests to reflect my
knowledge of the system at that time. If I miss a test case, it's
usually because I forgot about it. To me popping up the stack to the
feature specs at this point leaves the `Adder::Machine#sum` in a state
that is not fully reflective of our knowledge. We know the full spec, we
should finish it now (in the real world, I've seen methods left
incomplete as someone popped up the stack and never came back to finish
it as they were pulled onto something else).

As we've been doing, we write our test first. Instead of writing many
different test cases for each of our contexts (one for each of the
different things we could pass in: Fixnum, Float, String), we cheat. We
carefully pick a test case that merges all of these behaviors together.
Now there are some trade-offs we're making here:

  * When the test fails, it may be harder to pinpoint exactly which
    argument is messing with things
  * We don't have to duplicate the test cases for each context
  * We are trusting that this level of coverage is enough

In normal day to day activities, these types of trade-offs are made
constantly. If there is ever a bug encountered, go back and write a test
for it!

Here we find out that our implementation isn't actually correct. The
first error we encounter is one of passing an `Array` to `BigDecimal`.
This is the same error that our feature spec is now throwing at us. The
fix is simple enough: use `flatten` to make the `numbers` array one
dimensional. Note though that `flatten` is notoriously slow. We'll
accept this trade off for now as we never expect the `numbers` array to
be large. Nor is squeezing every once of speed out of this a priority.

Next we encounter an error that we've omitted precision for the float
when provided to `BigDecimal`. Since we want to support whatever
precision that the client gives us we use a little hack. By converting
the numbers into `String`s we leave it to `BigDecimal` to do the
conversions for us.

After these changes, everything is passing and we can continue.
Finish adder sum specs.

Based on our current understanding of the `Adder::Machine#sum` spec
there is one last case to test: passing a bad value and having it become
a zero. Our current implementation already handles this case for us!
(well technically `BigDecimal::new` does).

Always be suspicious of tests that pass the first time around. I like to
change the code under test to make the test fail to verify I'm not
losing my mind and that I have the proper understanding of what
mechanism is causing stuff to pass. However, in this case, the act of
passing the `String` to `BigDecimal` does this. There isn't much of a
code change we can make without breaking it all.

In this case, I open a `pry` session and manually verify that
`BigDecimal` is what is doing the conversion. That knowledge, combined
with the passing test, is enough _trust_ for me to continue.

Now that our spec is fully implemented, we pop up the BDD stack to the
feature spec. It's now passing too! So we remove the `wip` tag.