Do you know that feeling when you’re starting another query and this time you’re thinking “I won’t re-use this… this is a one-time thing…”. We both know you’re lying.
I said that because most of the time:
- you’re code is reusable
- you’re human and you forget stuff, so perhaps tomorrow you forgot something you realized how to do today
- I’ve never seen where you keep your scripts but I bet that needs a clean up
When you’re working on something, try to picture your future self. Your older self has probably no clue about what this *really_important_2018_script* project was. Is your older/wiser version happy while reading that? I don’t think so.
If you make an effort now to be more “tidy” with your code, here’s who will be happy:
- your future self
- your colleagues who read your code
- people who will take your job in the future and think “hey! this person don’t suck as much as I thought… just a little!”
How to add comments in SQL
Basically, there are two ways to add comments in SQL:
1- add “–” and start typing!
2- add “/**/” and write in between the stars.
No one is better than the other. The first option is usually for in-line smaller comment. The second it’s more for commenting out blocks of code or writing bigger comments in a way they will not be on one same line.
Initial comments
Personally, I believe comments are a good thing. It’s not something I do with every line, however, when I open a new query, I automatically add my comments.
Here’s how I like to start my scripts:
Important note: if you’re writing a stored procedure, remember to add this block of comments after your “CREATE PROCEDURE” statement. When you do so, the comment will show up when you right-click on the stored procedure and chose “Modify”. Otherwise it’s gone and saved only on your main script file.
Naming your file
Try to be descriptive when naming your file, and don’t abbreviate too much. The name you chose may seem relevant now, but again, ask yourself “is my future version hating me now?”. If the answer is yes, than chose something else.
If the script you are creating is part of a bigger project that involves other scripts, then try to start every file name with something that refers to the project itself.
For example: sp_AutomatedFinancialReports_CalculatingEmployeeSalary
Here’s what we know based on the file name:
- sp: this is a stored procedure
- AutomatedFinancialReports: project name that’s descriptive
- CalculatingEmployeeSalary: this is what your specific script will do as part of the project
Avoid at all costs using “new”, “old”, “final” and relative names on your file. This is not useful long-term. If you’re creating many drafts, I’d go with versions like “v1”, “v2”, or just add the plain date to your file name. But remember this is a temporary name, and that once you figure your “v23_final_new” file, you’ll change the name accordingly. Another trick is to move your thousand drafts to a, guess what, drafts folder. The idea is that your main project folder keeps your already tested and ready to go script.
This is some basic stuff I do everyday and I hope you find it useful. Do you add something else that you’d like to share? Leave a comment (:
Want to read this post in Portuguese? Check out this link.
See you later!
Camila Henrique 