Developers use comments within the code primarily for two purposes –
- Documentation (for posterity)
- Debugging (making quick comparisons of the impact of a change without discarding the original code)
It depends on the team’s culture and their coding standards as to how much they choose to comment for documentation. Ideally, there should be a change history included as a header at the top of the code and additional comments to highlight why a particular logic was used. Another developer (or even the original) can look at the code and understand what is it doing, but sometimes it is not apparent why was that particular implementation chosen over others. So it is a good idea to mention the rationale behind using a particular logic. Other interesting paradigms can be checked on the Wikipedia article on Comments in Programming.
TSQL supports two types of comments –
- Single-line comments: These start with a double hyphen ‘- -‘ and the rest of the code on that line till the new-line (or carriage return) character is considered to be a comment.
- Multi-line comments: These start with a ‘/*’ and end with a ‘*/’ either on the same line of the code or on another line and everything in between these two is considered to be a comment.
The implementation of comments has not changed much between various editions of SQL Server but there have been few considerations. The MSDN article for comments syntax in SQL Server 2000 mentions that comments cannot span multiple batches. If the batch delimiter keyword GO is within a multi-line comment then the ending */ will not be parsed correctly and cause syntax errors. The SQL Server 2005 or later versions could have issues when the ‘*/’ string is put in a multi-line comment. Try the code below in SQL Server 2005 or later versions to see an example –
DECLARE @s VARCHAR(10) /* SET @s = '*/' */ SELECT @s
Each comment type has its uses but I personally prefer and recommend using the multi-line syntax, even for short comments that could fit on a single line. My reason for that is that I frequently get requests to review queries and give suggestions on tuning them. Sometimes that query has been captured from DBCC INPUTBUFFER(spid) or the dm_exec_sql_text(sql_handle) DM function. Both of these do not preserve any formatting of the code. As a result I get the entire stored procedures’ code in one single long line!
I usually try to format such code using an excellent online code formatter by the name of SQLInForm. When the formatter comes across a double hyphen, it considers the rest of the line as a comment and leaves it as it is. At that point I have to make a choice either to painfully go through the remaining code and try to guess what is a comment and what is not. At times I send it back to the developer to provided a better fomatted code. Both these approaches increase the turnaround time for the whole tuning process.
If the developer had used the multi-line comment syntax in the first place, then the code formatter could have handled it and life would have been much easier.