SQL Homework – January 2020 – Document, document, document


January 1, 2020 by Kenneth Fisher

Happy New Year! It being New Year’s, at least by the Gregorian calendar, I thought we could make this month’s homework more of a New Year’s resolution. This month, at least, I’d like you to make a concerted effort to document your code. At the very least you need to have a few lines of comments at the beginning of every SP/view that says what it’s for. If you call another SP inside of a SP then you need to comment why and what you are doing. If you need to use a loop or a cursor explain your reasoning etc. Doing something complicated or unusual? A coding anti-pattern for a good reason? All of these things need to be documented.

Want an incentive other than this post? I was once offered a job specifically because I commented the code I wrote for them in my tech test. Let me repeat that. I was offered a job not because of the code (although it was correct) but because of the comments. And the comments were there because I was trying to make sure I could keep track of what I was doing.

Now, while you are busily documenting your code I want you to try to go one step farther. Document your processes. Do you have a common problem that occurs when you are on call? For example let’s say you have an ETL process that sometimes fails and just needs to be restarted, or a file moved and then restart it. Create documentation. That way if it’s 3am you just have to look at your document and know exactly what to do, no thinking required. And even better when the new person gets woken up at 3am they don’t have to call you to find out what to do.

Happy New Year!
and Happy Documenting!

4 thoughts on “SQL Homework – January 2020 – Document, document, document

  1. Simon Holzman says:

    Totally agree. The two things I would add are…

    1. Document the process in one of the pieces of code, if there are multiple pieces. In all of the other pieces, state which piece of code is the ‘Master’ that details the whole process and lists all of the other pieces.

    2. Ensure that the comment is a part of the stored code, if possible. In other words, put it in the body of the Stored Procedure rather than as a header. You might not have access to the original script file and this means that you don’t need to. (This isn’t easy with Views but you COULD have a criteria WHERE ‘The Master documentation for this is in the xxx Stored Procedure’ ‘as of 2nd January 2020’)

    This is useful for all code but it is especially essential for SQL where the code may not even have any source files or can be edited by multiple people without any guarantee that they are using proper change control.

  2. […] along with last month’s documentation homework this month I want you to write a blog post. But Ken, what does writing a blog post have to do with […]

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Enter your email address to follow this blog and receive notifications of new posts by email.

Join 3,753 other subscribers

Follow me on Twitter

ToadWorld Pro of the Month November 2013
%d bloggers like this: