SQL Homework – January 2020 – Document, document, document4
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!
Category: Documentation, Microsoft SQL Server, SQL Homework, SQLServerPedia Syndication | Tags: Documentation, Microsoft SQL Server
4 thoughts on “SQL Homework – January 2020 – Document, document, document”
Leave a Reply Cancel reply
This site uses Akismet to reduce spam. Learn how your comment data is processed.
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.
That filtered out my Not Equals in the example View criteria – sigh !
Yea, that happens to me a lot 😀 You can use < and > instead though.
[…] 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 […]