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!