Slash Boxes
NOTE: use Perl; is on undef hiatus. You can read content, but you can't post it. More info will be forthcoming forthcomingly.

All the Perl that's Practical to Extract and Report

The Fine Print: The following comments are owned by whoever posted them. We are not responsible for them in any way.
More | Login | Reply
Loading... please wait.
  • 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.