- \n
- <\/li>\n<\/ul>\n
Single line comments start with a double minus. Any code or text on the right side of this sequence is regarded by SQL Server as a comment. The sequence must not necessarily start at the beginning of the line. The sequence can be located at any position within a line.<\/p>\n
-- Single Line Comment<\/pre>\n
To ease the effort for commenting multiple lines by using this syntax, SQL Server Management Studio (SSMS) offers two powerful short cuts:<\/p>\n
- \n
- Ctrl+K+C <\/strong>(with C<\/strong> for Comment)<\/li>\n
- Ctrl+K+U<\/strong> (with U for Uncomment)<\/li>\n<\/ul>\n
The second syntax for commenting multiple lines starts with a slash followed by an asterisk as an initiating sequence and ends with the reverse string as the closing sequence: an asterisk followed by a slash:<\/p>\n
\/*\nBlock Kommentar\n*\/<\/pre>\n
Any code between the initiating and a closing sequence is regarded by SQL Server as a comment.<\/p>\n
The initiating and the closing sequence can be located anywhere in the code. An initiating sequence must have a closing sequence.<\/p>\n
Both comments have in common that comments are by default displayed with green font color<\/p>\n
As so often … developers argue whether one or the other syntax serves best for adding inline documentation.<\/p>\n
I prefer the single line syntax for the following reasons:<\/p>\n
- \n
- Each line that is prefixed with the single line sequence can be directly identified as a sequence. When using the second syntax you may identify a single line as a commented line solely by the font color. With that the single line syntax distinguishes any comment clearly from any uncommented code without paying attention to the font color.<\/li>\n
- Using the column editor (see Functional Design (Aesthetics) of SQL<\/strong>) makes it very easy to apply this syntax to multiple lines in one step.<\/li>\n
- Additionally, the single line syntax serves best as a structuring element within a large SQ statement.<\/li>\n<\/ul>\n
Examples<\/h2>\n
This chapter provides three examples for inline documentation:<\/p>\n
- \n
- No uniform usage of inline documentation<\/li>\n
- Parallel inline documentation<\/li>\n
- Template for Inline Documentation<\/li>\n<\/ul>\n
No uniform usage of inline documentation<\/h3>\n
The following example shows an inline documentation, that can be often found. There is neither a uniform usage of either syntaxes nor is there a uniform indentation of comments. All comments extend to the entire line. Despite a good formatting of the actual statement, this medium-complex statement is difficult to read due to the unstructured inline documentation. The complexity of the SQL statement lies in the use of a recursive common table expression (CTE) and the corresponding documentation of this feature and its use. The statement can be executed in the database AdventureWorksDW2017<\/strong>.<\/p>\n
![\"\"](\"https:\/\/staging.sql.marcus-belz.de\/wp-content\/uploads\/2018\/07\/post00140001-457x1024.png\")
<\/a><\/p>\nSource<\/a><\/p>\n
Parallel inline documentation<\/h3>\n
A reengineered version of the same statement includes a parallel inline documentation. A parallel inline documentation is characterized by the fact that a block for the inline documentation is provided on the right behind the statement. This inline documentation uses the single line syntax. The commenting sequence strings are left justified across all lines.<\/p>\n
![\"\"](\"https:\/\/staging.sql.marcus-belz.de\/wp-content\/uploads\/2018\/07\/post00140002-1011x1024.png\")
<\/a><\/p>\nSource<\/a><\/p>\n
A parallel inline documentation can be described as follows:<\/p>\n
- \n
- The actual SQL statements is compact.<\/li>\n
- The SQL statement is not interrupted by any inline documentation and does not harm the readability.<\/li>\n
- If a comment refers to the line of code on the left side, this direct link is indicated by using a special sequence of characters (e.g. >><\/strong>).<\/li>\n
- Any comment that requires a longer explanation appears to be mor readable when using bullet point (e.g. #<\/strong>).<\/li>\n
- The length of a line including the comment should not be too long to avoid. Any line, that can not be displayed fully on the screen requires the developer to navigate horizontally. Horizontal navigation is much more difficult to perform compared to a vertical navigation using the mouse wheel or the page up<\/strong> and page down<\/strong><\/li>\n<\/ul>\n
Template for inline documentation<\/h3>\n
The following example shows a full blown inline documentation of a SQL statement including comments on how to use the parallel inline documentation.<\/p>\n
![\"\"](\"https:\/\/staging.sql.marcus-belz.de\/wp-content\/uploads\/2018\/07\/post00140003.png\")
<\/a><\/p>\nSource<\/a><\/p>\n","protected":false},"excerpt":{"rendered":"
- Any comment that requires a longer explanation appears to be mor readable when using bullet point (e.g. #<\/strong>).<\/li>\n
- Additionally, the single line syntax serves best as a structuring element within a large SQ statement.<\/li>\n<\/ul>\n
- Ctrl+K+U<\/strong> (with U for Uncomment)<\/li>\n<\/ul>\n
- Ctrl+K+C <\/strong>(with C<\/strong> for Comment)<\/li>\n
![\"\"](\"https:\/\/staging.sql.marcus-belz.de\/wp-content\/uploads\/2018\/07\/post00140001.png\")
<\/a><\/p>\n