This editorial was originally published on 14 May 2015. It is being re-published as Steve is at a SQL in the City Summit.

Documenting code isn't a task that many people enjoy. Those of you that have been through a computer science curriculum probably added lots of verbose, and obvious, comments to code. It's probably unlikely that you ever found much value in the comments in a paying job.

There are all sorts of ideas on how to document your software, writing good comments, and even refactoring code to remove unnecessary comments. I'm sure that if we put five developers in a room, we'd end up with eight different ways to comment code that would be debated, with no agreement on how to proceed.

I ran across an interesting approach from Ed Elliot on documenting your code with unit tests. I hadn't thought about the tests providing some documentation, but it's an interesting idea. I'd have to work with the concept a bit, but I'm skeptical I'd get enough information from unit tests to ensure I understood what a stored procedure was doing, especially if I had 10 tests for a long procedure.

I do think unit tests are important, and perhaps in conjunction with some type of code header that gives the requirements the procedure fulfills, I'll get enough information to understand the code.

I don't have a universal solution that I think will work in most situations, but I do think that having a tool like intellisense or SQL Prompt helps you self document code with expressive names for columns, variables, and aliases. If nothing else, those phrases for variables can clue the next programmer in to what is happening better than single letter names.