The writing challenge this month is from fellow MCM Wayne Sheffield (@DBAWayne), and is remarkably special, as it marks ten years since T-SQL Tuesday started. He asks us to talk about a time when we’ve wondered what someone was thinking when we’ve read their code.
…except that I’m not a fan of writing about other people’s code, so I’m going to write about some times that I’ve read my own code and had that same thought. In other words, I’m going to write about my documentation style.
You see, whether it’s me reading back some code that I’ve written or whether it’s someone else reading some code that I’ve written, the main thing that I need to communicate is what I was thinking. Whereas a lot of the documentation I see is more about what I’m doing – which should hopefully be clear to anyone who can understand code.
I see comments like this:
|
1 |
set @i += 1; --Increment @i |
And I want to see a comment like:
|
1 |
set @i += 1; -- Increment @i here rather than at the end of the loop so when we finish looping, it's still on the one that didn't caused the stop condition |
I get that it’s more text, but I need to know the WHY, not the WHAT. It means I’m less likely to describe what the query actually does, but more likely to describe why I’ve chosen a more controversial construct.
This definitely applies if I’m grouping by a column that isn’t in the SELECT clause, providing an inverted predicate, doing a double OUTER APPLY (SELECT TOP (1)…), or even providing a table or join hint. I might hope I know what I’m doing, but I also want to make sure that someone else (maybe even future me) has the faintest clue too.
Thanks for hosting, Wayne.
