Documentation Driven Development

A lightning talk about documentation

Transcript

1. DDD Documentation Drive Development
2. TomDoc http://tomdoc.org/
3. # Public: Duplicate some text an arbitrary number of times. # # text - The String to be duplicated. # count - The Integer number of times to duplicate the text. # # Examples # # multiplex('Tom', 4) # # => 'TomTomTomTom' # # Returns the duplicated String. def multiplex(text, count) text * count end
4. 1- Find a method you don’t understand
5. def active? return true if ( Time.now.utc > self.start_date && self.end_date.nil?) return (Time.now.utc > self.start_date && Time.now.utc < self.end_date) end
6. 2 - Write a documentation to it
7. # Public: checks if the campaign is active. # # Return `true` if the campaign started in the past and the end date is # `nil` or is in the future. def active? return true if ( Time.now.utc > self.start_date && self.end_date.nil?) return (Time.now.utc > self.start_date && Time.now.utc < self.end_date) end
8. 3 - See if tests match the documentation
9. it "returns true if the campaign is active right now" do active_voucher_campaign.should be_active end it "returns false if the campaign's end date is in past" do inactive_voucher_campaign.should_not be_active end it "returns true if the campaign has started in past and there is no end date" voucher_campaign_without_end_date.should be_active end
10. 5 - Refactor
11. # Public: checks if the campaign is active. # # Return `true` if the campaign started in the past and the end date is # `nil` or is in the future. def active? now = Time.now.utc return true if (started_in_past?(now) && self.end_date.nil?) return (started_in_past?(now) && now < self.end_date) end # Internal: checks if the campaign started in the past. # # time - the time you want to compare. def started_in_past?(time) time > start_date end
12. 6 - Repeat
13. # Public: checks if the campaign is active. # # Return `true` if the campaign started in the past and the end date is # `nil` or is in the future. def active? now = Time.now.utc return true if (started_in_past?(now) && self.end_date.nil?) return (started_in_past?(now) && will_end_in_future?(now)) end # Internal: checks if the campaign started in the past. # # time - the time you want to compare. def started_in_past?(time) time > start_date end # Internal: checks if the campaign will end in the future. # # time - the time you want to compare. def will_end_in_future?(time) time < end_date end
14. # Public: checks if the campaign is active. # # Return `true` if the campaign started in the past and the end date is # `nil` or is in the future. def active? now = Time.now.utc started_in_past?(now) && (self.end_date.nil? || will_end_in_future? (now)) end # Internal: checks if the campaign started in the past. # # time - the time you want to compare. def started_in_past?(time) time > start_date end # Internal: checks if the campaign will end in the future. # # time - the time you want to compare. def will_end_in_future?(time) time < end_date end
15. # Public: checks if the campaign is active. def active? now = Time.now.utc started_in_past?(now) && (self.end_date.nil? || will_end_in_future?(now)) end # Internal: checks if the campaign started in the past. # # time - the time you want to compare. def started_in_past?(time) time > start_date end # Internal: checks if the campaign will end in the future. # # time - the time you want to compare. def will_end_in_future?(time) time < end_date end