use Perl

• Specification- and Test-Driven Development (Score:1)

  by kid51 (5328) on 2008.07.21 13:49 (#63984) Homepage Journal

  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.

  Reply to This

  • Re: (Score:1)

    by zby (4817)

    I've made a list of online resources on API design [blogspot.com] - I think all of them advice writing APIs and example code using that API before writing implementation.