This is going to be a quick guide, and it's going to be all about something that's not related to running queries but more in regards to documenting your code. Today we're going to talk about how we can comment to our SQL queries.

Now there are two different ways of doing it, and I'm showing you both, and I'm going to give us a little line here and say that this is a summary report for states. I am going to say this is a summary report for the counting states. So this is a multi-line comment. One way of doing this in my SQL Workbench is just selecting everything and everything that you want to make a comment and then just hit command + slash.

So just do that, and it converts it into a comment, and that is all you need to do for adding multi-line comments. Now there are also times where you may want to add a comment inline. So for that what the standard convention is to use the hash mark. Here if I want to say that this is and I would never specifically do this, but so that you can see the syntax I'd say for the guide's table. Obviously, it says from guides, So I think it's pretty self-explanatory but that is the syntax for inline comments and notice how this greys it out.

So it's pretty clear what's going on here, and if I select everything and run it, then it's still going to run just like normal. If I run this, it's going to run, and it runs our same query.

That is how that side of it works. One thing I want to mention before ending this guide and I know it was a short one just because it wasn't about functionality. It was more just about some syntax items for being able to comment in your code.

There is a rule of thumb when it comes to writing documentation and writing comments, and that is that code changes, but comments don't always change with it. What that essentially means is that it would be easy for me to come here and to change each one of these as we did in this one to cities and notice how the comment obviously didn't change. The comment is just a hardcoded static piece of documentation inside of the code.

Now, if someone comes in the future and if it's just three lines of code, not a big deal but if you have a 40 line query and you add comments to it to describe exactly what it does, and then you go and change the code but don't update the comments. Then you could cause some really big issues.

Say that you did something that wiped out a bunch of users. But originally the script was supposed to be for some other type of functionality and it wasn't until you changed it later that, that all happened. So you need to be careful when you're commenting.

I kind of as a rule of thumb I try not to make a lot of comments. Mainly for that specific reason because I've seen so many legacy applications where the comments were never updated, and so it became incredibly confusing on what was going on because you'd read one thing, but then the code seemed to tell a little bit different story.

So just always keep that in mind whenever you're writing comments. If you are going to leave comments, then make sure that you continue to go back and update them. There should be a one to one change if you change a piece of functionality in your script. You should also change the comment to make sure it's always updated. So that is how you can add comments in the SQL.

Code

USE devcamp_sql_course_schema;

-- This is a summary report
-- for counting states
SELECT addresses_state, COUNT(addresses_state)
FROM addresses
GROUP BY addresses_state;

SELECT addresses_city, COUNT(addresses_city)
FROM addresses
GROUP BY addresses_city;

SELECT guides_users_id, SUM(guides_revenue)
FROM guides # For the guides table
GROUP BY guides_users_id;