Yeah, yeah, I know. I'm a little late to the game. I've known in theory that
TDD is a good idea for quite some time. But, as they say, "In theory, theory
and practice are the same".
I needed to write a plugin module for work today. I stubbed out the module
using module-starter and wrote the POD. Writing the API documentation first
had the nice effect of keeping it simple. I don't like writing documentation,
so I'm not about to document publicly something that might not be useful.
Then I wrote the tests. I like breaking things, and thinking about how to
break things. Thinking about how to break things that don't exist yet was
fun! Writing tests made me think through the API in ways that I hadn't when I
wrote the POD. Based on the thinking I had to do when writing tests, I ended
up re-writing sections of the documentation to clarify how certain methods
should act.
Then I wrote the code. I thought that I only wrote enough code to pass the
tests, but once the tests were passing I dug in and re-factored the code,
shortening it a fair bit.
I'm a TDD fanboy, coming out late!
I stubbed out the module using module-starter and wrote the POD. Writing the API documentation first had the nice effect of keeping it simple.
...
Several years ago I gave a talk to New Orleans Perlmongers on writing a module in the CPAN style. As a gag, I said, "First you write your documentation, then you write your tests, and only then do you write your code."
It was a gag then, but over the next couple of years I began to wonder, "What if I really did write my documentation first?" I.e., what if I wrote myself a specification first.
I tried it and I liked it. With practice, I was able to write 80% of the POD for a module before writing a single line of code. As you discovered, it forced me to think about the interface very early on in the process.
Then I wrote the tests.
.... Writing tests made me think through the API in ways that I hadn't when I wrote the POD. Based on the thinking I had to do when writing tests, I ended up re-writing sections of the documentation to clarify how certain methods should act. Then I wrote the code. I thought that I only wrote enough code to pass the tests, but once the tests were passing I dug in and re-factored the code, shortening it a fair bit.
The experience you describe is one I have had repeatedly since I started writing in a more specification-driven and test-driven manner. Thanks for sharing it.
Re:Specification- and Test-Driven Development
zby on 2009-07-28T20:28:35
I've made a list of online resources on API design - I think all of them advice writing APIs and example code using that API before writing implementation.
