Introduction

Most of us usually have pre-defined coding standards to be followed. How many of us have pre-defined commenting standards?

Comments are optional. Comments are non-executing. Therefore we tend to over relax when it comes to providing comments to our code. Let us delve into a few aspects of commenting.

Types of Software documentations

• External documentation
• Internal documentation

External Documentation
External documentation consists of specifications, ERDs, data dictionary, etc., that are maintained outside the source code.

Internal Documentation
Internal documentation is comprised of comments written by developers within the source code at the development time.

Internal documentation important as it cannot be lost and is within immediate reach of the developers working with the code. It helps read straight through the code and gain a reasonably good understanding of the code.

The challenge faced with internal documentation is ensuring the comments are maintained and in sync with the source code.

Types of Comments

• Multiple-Line (Block) Comments
• Single-Line Comments
• Trailing Comments

Multiple-Line (Block) Comments
Multiple-Line (block) comments are used to provide brief descriptions spanning across multiple lines and appear at the beginning of each file and before each method. However, multiple-line (block) comments can also appear within the body of the method in which case they should be indented to the same level as the code they describe. Multiple-line (block) comment should be preceded by a blank line.

Single-Line Comments
Single-line comments are used for short descriptions and appear on a single line indented to the level of the code they describe. A blank line may precede s single-line comment.

Trailing Comments
Trailing comments are very short descriptions and appear on the same line as the code they describe. Trailing comments should be shifted far enough to separate them from the code. If these trailing comments appear more than once in the code, they should all be indented to the same tab setting.

Types of Comment charaters

Microsoft SQL Server supports two types of commenting characters:

• -- (double hyphen)
• /* ... */ (forward slash-asterisk character pairs)

-- (double hyphen).

• Everything from the double hyphens to the end of the line is part of the comment.
• For a block (multiple-line) comment, the double hyphens must appear at the beginning of each comment line.
• These comment characters can be used on the same line as code to be executed, or on a line by themselves.

/* ... */ (forward slash-asterisk character pairs).

• Everything from the open comment pair (/*) to the close comment pair (*/) is considered part of the comment.
• For a block (multiple-line) comment, the open-comment character pair (/*) must begin the comment, and the close-comment character pair (*/) must end the comment.
• These comment characters can be used on the same line as code to be executed, on lines by themselves, or even within executable code.

Remark: Including a GO command within a comment generates an error message.

Illustration

/* First line of a multiple-line (block) comment.
   Second line of a multiple-line (block) comment. */DECLARE @PersonId AS int-- This is a trailing comment 
DECLARE @PersonName AS varchar(50)-- This is a trailing comment 
SET @PersonId = 0
SET @PersonName = ''
-- First line of a multiple-line (block) comment.
-- Second line of a multiple-line (block) comment.
WHILE @PersonId < 50
BEGIN
-- This is a single line comment.
INSERT INTO Persons (PersonId, PersonName)
VALUES (@PersonId, @PersonName)
SET @PersonId = @PersonId + 1/* This is a trailing comment */END
-- Comment within an executable code.
SELECT PersonId, /* FirstName, */ PersonName
FROM Persons

Do's & Don'ts of Commenting

Comment as you code. The code which is understandable today probably may not be so clear when you revisit after some days.

Update the comments when modifying the code. This will avoid confusions during the future program code maintenance.

Comment to explain the purpose of the code. Use complete sentences when writing comments. The comment should not add ambiguity.

-- Data insertion/modification is not allowed when a transaction is in an uncommittable state.

Provide comments for the code that consists of loops and logic branching. Loops and logic branching are the key areas in the code. Providing comments for these will assist the source code reader in determining the flow of the code.

-- Data insertion/modification is not allowed when a transaction is in an uncommittable state.
-- Return if inside an uncommittable transaction.
IF XACT_STATE() = -1
BEGIN
PRINT 'Cannot log error. Current transaction is in an uncommittable state.'
RETURN
END

Avoid commenting self explanatory code. This can clutter the code. Provide comment for the code that is not obvious.

-- Increment the count by 1.
@iCount = @iCount + 1

Avoid inappropriate or humorous comments. Such comments reflect an unprofessional approach.

-- this is a fundu logic.
UPDATE #rowset 
SET@List = list = CASEWHEN @AddLine1 <> AddLine1 then PrefDesc
ELSE @List + ', ' + PrefDesc 
END,    
@AddressLine1 = AddressLine1

Avoid copying and pasting comments. There are chances one may forget to update the comments after cut and paste operation. This can lead to confusions when the code is revisited.

Prior to deployment remove all temporary and/or off the point comments. This will avoid confusions during the future program code maintenance.

Prior to deployment comment or remove the PRINT statements as applicable. This will boost network peformance as PRINT statements return the messages to the ADO, OLE DB and ODBC applications as as an informational error.

-- PRINT 'comment your print messages before deployment'

Comment on bug fixes. This serves as a reference to the issues idenfied in the testing process. Provide details such as developer who has fixed the bug, the date when the bug was fixed, a reference to bug tracker, if any, and and a short description on the bug fix.

-- [SD 05/29/2006]: DefectId #123
-- A short description of the defect and/or fix 

Separate comments from the comment characters with a white space or a blank line. This improves the readability of the comments and also the code.

-- Spearate cooments from comment characters with a white space
/* Spearate cooments from comment characters with a white space *//* 
  Spearate cooments from comment characters with a blank line
*/

Avoid framing block comments. It looks attractive initially but is difficult to maintain especially during the maintenance as it passes many hands.

/*************************************************
* Procedure Name :                          *
* Description :                  *
*                                    *
*                                       *
*************************************************/

Develop a standard header for stored procedures, views and user-defined functions. Include details such as a brief description of the object, specification document, author, date created, change history, etc.

Throughout the application, develop and maintain a uniform style of commenting. This improves the readability of the code and represents a professional approach.

In a Nutshell

Comment your code.