Level Up 3: Understands how "writing the code you want to see" makes for better code

gistfile1.txt

1. Explain the theory around 'writing the code you want to see'.

At it's essence, "writing the code you want to see" means forgoing starting at the class level, whatever that may be, and working at the high level. This will produce much simpler interfaces between classes. Once you get the interfaces of the classes built, can you delve lower into each one, writing the logic, algorithms and data structures that will eventually form the classes of your application. 

Writing high level integration tests, and making them pass, leads to coding in this fashion. The tests will start you at a high level, and eventually tell you to delve deeper into the implementation of the application. This leads to a minimal implementation that consists of simple, expressive interfaces. 

2. Create a short gist illustrating a place where violating this rule would cause you to write worse code.

Suppose I am creating a blog application. If I don't start with integration tests, I would likely start at the model level. Because I don't know what the customer needs (which would otherwise be defined in the Integration tests), I would have to guess what is needed in the model.

Perhaps I'd need an Article model, with several attributes:

rails g model Article title:string text:text date:datetime published:boolean publish_date:datetime author:string

I would then create unit tests for the details of the model.

However, down the road, I find out that the customer doesn't care about the author. Perhaps they are like The Economist and use anonymous authors. By starting at the low level implementation, I've overbuilt the model. And I've probably created an Author model with associations between it and the Article Model. Furthermore, I've probably built validations, controller logic and views that all use an Author. 

If I had started out agreeing to this simple Feature with the customer, I would have avoided a lot of unnecessary code:

Feature: Add Articles
  As an administrator
  I want to add articles
  So the content is shown on the blog

  Scenario: Get articles
    Given an article supplied as a JSON file
    When I add the article to the blog
    Then I should see the article title and content