Self-Documenting Unit Tests

We have been practicing agile for more than a few years now and getting better as we move along, or at least that’s the goal and a desired expectation from the team; rightfully so since humans typically learn from experience. We jumped on the notion that by going agile, we can certainly reduce the mostly obsolete documents that managers/developers strive to keep current (or not), and fail. So the idea of having self documented code and unit tests sounded encouraging, to say the least.

The inspiration for this blog entry is not to comment about the want of having comments within code, since there is unquestionably no need, even though that’s a very hot unresolved topic. A very personal opinion, and I agree with folks out there, for having code comments is when you would like to proudly apologize for your work. “I so am superciliously sorry for writing this code, since I and only I can read it, lest you shall read the comments that I wrote“.

The inspiration for this blog entry is really to better understand how we can write self-documenting code, and very specifically the unit tests. We should take pride in the fact that new developers on the team are easily be brought on board to the design of the system merely by taking a look at the unit tests. In an ideal situation that may be the case, however in reality it’s more far fetched than it seems. I personally got baffled last week when I started to delve into a feature of our system developed a few months ago. We have strived to keep our unit tests clean and readable, more so functional. The unit/feature/system design obtained by practicing TDD certainly would make all the sense having known the context under which it was established. The context is what defines the behavior of the system, it is what goes on to be gloriously enbraced by the domain model and it is what helps determine the overall design of a system. Best practices of appropriately naming variables, methods, classes etc. are all part of establishing a clear context, which in turn provides clarity and the most needed self-documentation.

In comes BDD or Behavior Driven Design and suddenly there is light, literally shone on the context. As my colleague Joe O talks in his post, and Scott Bellware exhibits the BDD Extension Methods in Orcas that he has been playing with, and the industry in general, behavior as expressed by context has become the most focussed aspect of writing software, more importantly the unit tests and everything follows suit.

I firmly believe that “comments within code” issue can never be resolved, however for those like me who would rather write simpler code BDD is the way to go.