Overview
Documentation should be an inherent part of any database development project. Virtually everybody would agree with this. However, documentation is usually the first goal to be a victim of project pressure. “If you want to know what the code does, have a look at the code.” This is a very common view on missing documentation. But, not everybody is capable of write SQL statements or even read SQL statements. Pressure in projects is often a poor excuse for missing documentation. As of my experience, the main reason for missing or incomplete documentation is as simple as that: No one likes to write a documentation.
Inline documentation is a special form of documentation. Any code should contain a minimum of Inline documentation, especially when a separate documentation is not available. If a reasonable inline documentation is missing too, then the application is nearly not maintainable when the developer is no longer working for the company.
At the time of development of a SQL statement, the developer may have clarified all essential questions and the knowledge in his or her mind. However, this knowledge is fleeting. After just a few weeks, it is already difficult for her to understand complex statements. The situation in a multi-developer project is even more problematic.
This article introduces an uncommon but powerful approach for inline documentation: a parallel inline documentation.
Type of inline comments
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.
-- Single Line Comment
To ease the effort for commenting multiple lines by using this syntax, SQL Server Management Studio (SSMS) offers two powerful short cuts:
- Ctrl+K+C (with C for Comment)
- Ctrl+K+U (with U for Uncomment)
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:
/* Block Kommentar */
Any code between the initiating and a closing sequence is regarded by SQL Server as a comment.
The initiating and the closing sequence can be located anywhere in the code. An initiating sequence must have a closing sequence.
Both comments have in common that comments are by default displayed with green font color
As so often … developers argue whether one or the other syntax serves best for adding inline documentation.
I prefer the single line syntax for the following reasons:
- 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.
- Using the column editor (see Functional Design (Aesthetics) of SQL) makes it very easy to apply this syntax to multiple lines in one step.
- Additionally, the single line syntax serves best as a structuring element within a large SQ statement.
Examples
This chapter provides three examples for inline documentation:
- No uniform usage of inline documentation
- Parallel inline documentation
- Template for Inline Documentation
No uniform usage of inline documentation
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.
Parallel inline documentation
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.
A parallel inline documentation can be described as follows:
- The actual SQL statements is compact.
- The SQL statement is not interrupted by any inline documentation and does not harm the readability.
- 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. >>).
- Any comment that requires a longer explanation appears to be mor readable when using bullet point (e.g. #).
- 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 and page down
Template for inline documentation
The following example shows a full blown inline documentation of a SQL statement including comments on how to use the parallel inline documentation.
