Skip to main content

Documentation? You mean tests?

"I hate writing documentation!"

I've seen more than a few programmers say this.  To be honest, I've been guilty of saying it occasionally.  This post isn't about convincing you to like writing documentation.  I already wrote that post.  This post is about something I was talking to a coworker about just the other day.

Tests are documentation

I don't just mean that like when other programmers say it.  "Tests are one form of documentation."  This is much bigger than that.  When you test correctly and thoroughly, it's better than documentation.  That's when sh*t gets real.  I talked a bit about testing before, but what I said was only a piece of the whole.  Tests are the best form of documentation there is.  When you test code you don't understand, the test is a window into what you were thinking at the time.  It shows how the code works when it's done, but only by showing how you figured it out.  How many times have you looked at a piece of code and thought "What was he/she thinking when he/she wrote this?"  That's exactly what a test clarifies.

I'm not talking about TDD, but I am talking about testing.  I have yet to effectively use TDD.  It feels like predicting the future.  I don't know what I'll need to write before I write it, so I write it, then test it.  But I do test it.  I write End to End Tests, Unit Tests, and Acceptance Tests.  And, I demand nearly 100% code coverage.  I don't test generated code, but all of my code is tested, and well tested at that, I'm talking about testing by passing null parameters, and even with junk data.  I judge the quality of a Solution based on the size of the testing Project. Why?  Because if I ever don't know how something works, I can just run the tests for it and know everything about it.  (In fact, I'd love to see VS add to the context menu "Run Tests that Include this Method")

Tests are better than other technical documentation forms

While automated testing is useless at making end user documentation, this form of documentation is more detailed than standard technical docs, and on top of that it changes as the code changes, so it's always up to date.  More than that, it also gets checked into source control, so you can see the historical documentation side-by-side with the historical code.  This form of documentation grows with your code, it is "living" documentaiton.  More than anything else, it's ACCURATE.  There's not a 10 year old piece of paper suggesting that Server XYZ currently hosts the database for this project.  It's all there and you can see proof that this is how things work.  It's beyond documentation.  It's amazing when done properly.

It's not going to happen overnight

Do not imagine this is some magic wand that you can wave.  I'm working on a 3 week contract that I opened up a Solution with 0 tests on my first day.  While building code for the project I've only had time to write about 3 tests (by the end of week 2).  This is something you should implement on any new projects and work to implement over time on old projects.  But as a result, you'll never have to be afraid of making a change again.  Can you imagine that?  I know I would love to be in that position.


Popular posts from this blog

Teams and Complexity

Let's pretend you're a car mechanic (I don't know, maybe you are).  But you don't work at some shop in town, you work at a bigtime auto-maker onsite at the factory.  You help build cars from scratch.  You work with a lot of other car mechanics, and various engineers of different levels.  If we were looking at the 1910s, you might be working for Henry Ford on one of the first ever assembly lines.  Either way, you have a specific part of the car you're responsible for.  Your skills probably extend beyond that, and you might work on a different part of the car each day as your manager moves you around to keep the factory efficient.

One of your coworkers, Bob, is a superb engineer.  He is very good at building cars, far better than you, and he does it faster than everyone else.  Your boss really likes him.  You often get stuck after him in the assembly line, so you know exactly what sorts of things he does.  He's not sloppy, but he likes to do things his way.  He w…

Managing Programmers

Working with other programmers is tricky.  That said, it's nothing compared to the job of managing programmers.  One of my favorite quotes about Perl is that (paraphrased) "a Perl developer is like a rockstar.  Now imaging having a bunch of rockstars in one room together and you will understand why you don't want an entire team of Perl developers."  It's not about Perl here though. What's important to understand is that any developer worth his salt is going to be like a rockstar.  And yes, there are a lot of professional developers out there who aren't worth their salt, but that's for another post another day.  Rockstar may not be the right term here, but think of it this way.  These guys are smart.  They may not be geniuses, but there's going to be things that they know that you don't and probably never will.

I've seen it more than once and it's not going to make some Product Managers happy, but I'm going to state a fact, an eleph…

Managing Developers is HARD

I've been a software dev for a long time.  I've also been running my own software company for a few years now.  This is important information because of why I do these things.  I am a sofware developer because I love learning.  I slack off when doing a job that bores me, and software development always has something new to experience which keeps me excited and interested.  Why start a software company then?  That puts me in the role of manager rather than developer.  The truth is simple.  I've worked for a lot of companies, and I don't see any of them doing a great job of managing their software development.  That's not to say none of them have done a good job, but no one out there seems to be doing a great job.

How are they different?
A lot of companies get this part right.  Software developers are different from other employees.  The distinction is important in the same way it's important to acknowledge that an insurance agent is different from a construction…