Wednesday, December 28, 2005

Intent 0.4 - Intents, Stories and Facts

I have been keeping myself busy around christmas time.  I have corrected quite a few points of Intent and Proze, I have added a couple of examples, extended the functionalities and improved the layout.

You can download Intent-0.4 from RubyForge.

Once you have downloaded the package and made it available in ruby's load path you can run some of the samples in the demo directory.

I have already detailed intent_of_mathematics in another post, but it's worth to point out a couple of changes.
For a start I have added support for Facts.  A fact is a lazy developer's way of writing test.  You get some code that works and you literally save its context and its results, allowing you to freeze the implicit intent of this code.

This is not really intent-first development, but it is still a step towards capturing intent.

The following code records a fact about divisions:

fact!("Result of Division"){
    given "area",   a = 100
    given "height", h = 5 
   
    follows "base", a/h 
}

the fact get saved under the "facts" subdirectory as Result_of_Division.fact.xml. The xml looks like this:

<fact id='Result of Division'>
    <area>100</area>
    <height>5</height>
    <base>20</base>
</fact>

I tried to make it readable and understandable on its own, so that even a different developer will be able to understand the intent of that fact.

If the question mark of the fact call gets changed to a question mark (or simply removed)

fact("Result of Division"){ ...

then we switch from recording the fact to verifying that the fact is still true.

When I run a reality check on the intent (F5 in SciTe from the intent file) I get the following report:

---------- Reality checking Adding One ----------
Consistent intent: ..1..
Consistent intent: ..2..
Consistent intent: ..3..
---------- Reality checking Commutative Property of Addition ---
Consistent intent: ..3..
Consistent intent: ..5..

which means that the early intents are ok.

---------- Reality checking Comparison - Lesser Than ----------
Consistent intent: ..true..
**BROKEN** intent
    expected     ->false<-
    but got      ->true<-

    see: intent_of_mathematics.rb:14
            D:/apps/ruby/lib/ruby/1.8/intent/demo/intent_of_mathematics.rb:14:in

which points out a broken intent and allows you to jump direcly to the offending intent code:

intent_of("Comparison - Lesser Than") {
    expect 0 < 1
    expect 1 > 2
Our division fact returns the following:

---------- Reality checking Result of Division ----------
Consistent intent: ..'area: 100'..
Consistent intent: ..'height: 5'..
Consistent intent: ..'base: 20'..

we see that our saved fact has not been violated.

The multiplication unfortunately is broken:

---------- Reality checking Result of Multiplication --
Consistent intent: ..'base: 20'..
Consistent intent: ..'height: 5'..
**BROKEN** intent
    expected     ->'area: 101'<-
    but got      ->'area: 100'<-

    see: intent_of_mathematics.rb:46
            D:/apps/ruby/lib/ruby/1.8/intent/demo/intent_of_mathematics.rb:46:in

as we can see the area is wrong..

------------ Prozing ------------
prozing intent_of_mathematics.rb ...
---------------------------------


Then the intent gets prozed and produces a readable prozed file:

require 'intent/all'

intent of "Adding One" 
     0 + 1  should be 1
     1 + 1  should be 2
     2 + 1  should be 3

....

intent of "Recognising Illegal Operations"
    expect exception ZeroDivisionError
        when trying to calculate
        5 / 0
   
story "Calculating the Area of a Triangle"
    base   = 10
    height = 5
    area   = base * height / 2
   
    expect 25, as area

....


fact "Result of Multiplication"
    given "base",   b = 20
    given "height", h = 5 
   
    follows "area", b*h + 1


fact "Result of Division"
    given "area",   a = 100
    given "height", h = 5 
   
    follows "base", a/h 

Intents are supposed to capture small grained intentions as a design device.

Stories are descriptions of typical cross-functionality scenarios.

Facts are frozen representations of implicit intent.

In the next release of Intent I will also add Snapshots, an even rougher way of capturing intents.  A snapshot will intercept and memorize a set of input and output streams (puts and gets) and will save them as unqualified facts.

What I would like to do is to create a full development path that goes from raw implicit-intent snapshots to full fledged small granularity intents.

I envision the following sequence:

snapshot --> fact --> story --> intent

I was forgetting the final report.   I'll adjust it a bit so that it fits on the web page:

--------------------
Broken Expectations
---------------------------------------------------------
 * intent: Comparison - Lesser Than - #2: expected false, but was true
 * fact: Result of Multiplication - #3: expected area: 101, but was area: 100
---------------------------------------------------------

---------------
Broken Intents
---------------------------------------------------------
 * Comparison - Lesser Than
---------------------------------------------------------

---------------
Broken Facts
---------------------------------------------------------
 * Result of Multiplication
---------------------------------------------------------

we also get a nice report for each category and an average of expectations per intent (a good proxy of intent granularity and expressiveness)

 ----------------
Reality Checking
---------------------------------------------------------
    intents: 4                stories: 2            
---------------------------------------------------------
passed intents: 3/4     passed stories: 2/2  
broken intents: 1       broken stories: 0     
----------------------------------------------------------
    facts: 2               expectations: 17
----------------------------------------------------------
passed facts  : 1/2    passed expectations: 15/17
broken facts  : 1      broken expectations: 2
-----------------------------------------------------------
expectations per intent: 2.3
--------------------------
    powered by >>Intent<<
--------------------------


Comments: Post a Comment



<< Home

This page is powered by Blogger. Isn't yours?