Here is a presentation i made to some of my colleagues on friday explaining my first apprenticeship task, my wiki, how i went about it, the problems i encountered and what i learnt from the whole experience.
See my Apprenticeship task presentation on youtube.
Tags: apprenticeship, bdd, coding, design patterns, presentation, tdd, wiki
Posted in i use tags, not categories | No Comments »
Just a quick update on licky, my little wiki apprenticeship task i’m doing. I realise that time has gone on and i haven’t talked about it as much as i might, plus i actually have some quite encouraging news to report now!
Last time i wrote, i was just starting to work on Pages and a PageFactory to find them or create them as necessary. Since then i’ve added a persistence strategy which saves wiki pages to the filesystem. I pass the desired directory to the strategy so that test pages can be kept separate from real pages. This was necessary as i wanted to clear out the test directory every time after use and i didn’t want to accidentally delete real pages.
After that little burst of progress i stalled for a long time as i knew i needed to start writing the web interface and i didn’t know where to begin. James gave me a good idea which was to set up a simple Webserver class that would wrap around the web server of my choice. I have chosen WEBrick for the time being, but it shouldn’t be too difficult to swap in another one later, probably with another strategy pattern. James suggested i start by visiting a page and looking for the text ‘Hello world’. I thought this was a good idea and so i started finding out about WEBrick servlets.
With that start i was suddenly able to leap ahead, testing and implementing everything i need so that my wiki is now able to create, show and edit pages through the web interface. I feel as if i am very close now. Possibly the only thing left to do is add a way to link between pages and then i can truly call it a wiki.
Test driving the development of this whole project has been extremely educational. I know i started off getting too involved in writing a test framework, so Enrique pulled me back and made me think of the simplest thing that could possibly work. I began with one method: assert_equal. That was enough in the beginning. As time went on i added two more methods: assert_true and assert_contains. When necessary i added useful debugging information to report failures. At the appropriate time i refactored the testing framework into a module that could be included into multiple test classes.
I know i also started thinking about the web server too early. I started off trying to work with ERB and templates, as i am familiar with Rails, and in the end all i needed was a few servlets. As Enrique made me realise, the most important part of a wiki is not that it runs on a web server. The most important thing is content. Pages, with content, saved to a file system. Having focussed on that and got a real solid, well tested mechanism for saving and retrieving pages, i knew that the WEBrick servlets could rely on the underlying framework, and when the time came, it did not let me down.
Tags: apprenticeship, coding, tdd, wiki
Posted in i use tags, not categories | No Comments »
Since i last wrote, i have gone in a few directions trying to get started with my apprenticeship wiki task, got a bit stuck, talked to Enrique a lot, thought a lot, and i think i’m on track now.
My first mistake was to focus on the test framework. I was pretty pleased with my given/when/expect framework, and it actually sort of worked, but it wasn’t really necessary for what i needed. In the spirit of “the simplest thing that could possibly work”, this is the bare minimum you need for a testing framework:
def assert_equal(actual, expected) puts actual == expected end
My second mistake was to get carried away with making a web interface. I learnt a bit about WEBrick and how to embed ERB into a web page. That will become useful later, but it was the wrong place to start. After i had done all that experimenting, i still didn’t have anything remotely like a wiki framework!
Enrique asked me, “what is the most important part of the wiki?” – the answer is: content. If i have no content i have no wiki. So i am making it as basic as possible: creating a Page object and assigning it some content. Then i am moving on to a PageFactory that has the responsibility of finding pages. The pages may be stored in a database, filesystem, or even just in memory. It doesn’t matter for the moment. Whatever i decide to use, the PageFactory will deal with it.
My progress is now on github so you can follow along with my progress if you wish. The repository is sermoa/licky – licky meaning ‘little wiki’! :)
Tags: apprenticeship, wiki
Posted in i use tags, not categories | 4 Comments »
Enrique has amended my task so that i cannot use any existing testing framework, not even Ruby’s built-in Test::Unit. However, i must practice test-driven development! Ha ha ha!
So here i am trying to ponder how to write a unit testing framework. Which is actually really nice because i get to decide the syntax i would like to use, and maybe – just maybe – i’ll come up with something that suits me really well and i’ll use again.
Enrique pointed me to the Given specification framework which i like because it uses the BDD ‘given/when/then’ approach for unit-level specifications. I’m already used to this kind of format for Cucumber features. Effectively, we use ‘given/then/when’ for Rspec, but it’s not made explicitly obvious. My comments in this trivial example should make it obvious:
describe "example" do
before do
@counter = 1 #(given)
end
it "increments the counter" do
@counter += 2 #(when)
@counter.should == 3 #(then)
end
end
Now i think i could make the ‘given/when/then’ more obvious, and i can also simplify it. I might actually change ‘then’ to ‘expect’, meaning i can do away with the ’should’ method. Effectively i’m saying that whatever is in the ‘expect’ block should return true, otherwise the spec fails. Here’s what i’m thinking of:
spec do
given { @counter = 1 }
when { @counter += 2 }
expect { @counter == 3 }
end
I suppose this is what people call a DSL – a domain-specific language. That is the kind of language i’d like to use to write my specs. I’ve never written a DSL before, but i’m excited by the idea of being able to write specs like this, so i’m looking forward to giving it a go!
A little voice in the back of my head is telling me i’m going to have to finally understand ‘lambda’ properly. Lambda is one of those things that never sticks in my head. I can look it up when i need to and blunder my way to making it work, but i never really understand what it’s doing or how or why. I have a suspicion that i’ll be making extensive use of ‘lambda’ in my testing framework! :)
Tags: apprenticeship, bdd, coding, learning
Posted in i use tags, not categories | No Comments »
I am pleased to say that today i have been offered an apprenticeship under Enrique Comba Riepenhausen and i have accepted! From this moment on we have entered into a formal mentor-apprentice relationship where i will learn as much as possible from Enrique, and Enrique will mentor me to become a better software crafter. I expect it to be hard work but very rewarding.
I am proud and honoured to have been given this opportunity. I am glad that it has become official because i need my learning to be accountable to somebody. I am great at starting new things but really bad at following them through. To be answerable to Enrique will be very good for me, and i know that there is a lot that i can learn from Enrique.
My first task is to write a wiki engine in pure Ruby, with no libraries other than a testing framework. So no Rails, no Sinatra, no Mongrel, no plugins. This is to teach me the real core of Ruby as a language, without relying on other people’s code for shortcuts.
I guess the first thing i need to figure out is how to make the application listen for HTTP requests. Which i can honestly say right now i don’t have the faintest clue! Let the learning begin!
Tags: apprenticeship, learning, software crafting, wiki
Posted in i use tags, not categories | No Comments »