A couple of weeks ago there was an internal seminar at work about Test-Driven Development. The seminar was held by one of the senior devs who has been doing TDD for a few years. As a part of the seminar he presented a few levels of TDD practice, corresponding to different "aha" moments.
One of the "aha" moments was the realization that tests are documentation. When I heard this I thought for a while if I had had this "aha" moment yet or not. I could see how tests could be considered documentation, but that was not how I primarily saw it.
However, about a week ago I actually had that "aha" moment, and then once again today. Last week I had to go through some complex import/export code that I had worked with maybe a month earlier. Since I had worked on the code not that long ago I thought that I would remember how the code was supposed to work. That was not the case. I found myself wondering if a specific behaviour was by design or if it was a bug. After a few seconds of thinking I realized that the tests could tell me ("aha!"). A quick look in the test fixture and I knew that the code worked according to spec.
Today I was setting up a new hobby project, and I was rewriting some old configuration code for Fluent-NHibernate, since that project is changing quite rapidly. I was writing the database configuration and tried to find the correct way to specify "integrated security" as login for a MS SQL Server connection. Intellisense showed that there was a "TrustedConnection()" method of the configuration object, but it had no XML comments.
A quick google search turned up the Fluent NHibernate SVN repository, so I though to myself that I might as well take a quick look in the source. The search function at google code found the unit test for TrustedConnection().
The test look as follows:
[Test]
public void ConnectionString_for_trustedConnection_is_added_to_the_configuration()
{
MsSqlConfiguration.MsSql2005
.ConnectionString(c => c
.Server("db-srv")
.Database("tables")
.TrustedConnection())
.ToProperties().ShouldContain("connection.connection_string" ,
"Data Source=db-srv;Initial Catalog=tables;Integrated Security=True");
}
Integrated security it is then. Unit tests to the rescue! ("aha!")
However, when it comes to public libraries and API:s like Fluent NHibernate I really think that there is no excuse for not writing XML comments. Documentation in Intellisense is such a productivity boost that it is a must have for all API:s.
From now on, I can say without a doubt that I believe that unit tests are documentation.
Comments