{
    "href": "/post/2004/12/09/code-tests-as-examples/",
    "relId": "2004/12/09/code-tests-as-examples",
    "title": "Code Tests As Code Tutorials",
    "author": "pmjones",
    "markup": "html",
    "tags": [
        {
            "href": "/tag/php/",
            "relId": "php",
            "title": "PHP",
            "author": null,
            "created": null,
            "updated": [],
            "markup": "markdown"
        }
    ],
    "created": "2004-12-09 18:28:16 UTC",
    "updated": [
        "2004-12-09 18:28:16 UTC"
    ],
    "html": "<p>Early in the development of <a href=\"http://phpsavant.com/\">Savant</a> (back when it was HTML_Template_Dummy) I broke the assign() method without knowing it, then distributed the source to early adopter testers.  Of course, they discovered the break right away.  Embarrassed, I wrote up a quick series of \"visual\" test scripts to run on each release.  They are not automated; basically, they instantiate Savant and print out the results of various method calls, which I then eyeball to look for problems.  While not optimal, and certianly not \"best practice,\" it's good enough most of the time.</p>\n<p>However, such \"eyeball\" tests seem to have an unexpected benefit.  I just got a comment from Alex at Sourcelibre saying:</p>\n<blockquote><p>In version 2.3.2, the directory ... Savant2/tests are really usefull. I almost always prefer examples to explanations, and these examples are just perfect.</p></blockquote>\n<p>Well look at that.  I wrote up code examples and I didn't even know it.  While it's not documentation per se, it appears to add a lot of value to the package.</p>\n<p>So now there's at least one more reason to write non-automated tests for your libraries: if the tests are designed to be human readable, not machine readable, then they can serve the purpose of testing **and** tutorial.</p>\n"
}