Click here to monitor SSC
SQLServerCentral is supported by Red Gate Software Ltd.
 
Log in  ::  Register  ::  Not logged in
 
 
 

Database Commenting Guideline

By Sachin Dedhia,

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 = CASE	WHEN @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.

Total article views: 6775 | Views in the last 30 days: 1
 
Related Articles
ARTICLE

A simple trick for “Block Comment” syntax in SSMS

Make your comment blocks much more useful, in a surprising number of ways

FORUM

Erwin: propagate comments to multiple tables.

Erwin: propagate comments to multiple tables.

ARTICLE

Documenting Stored Procedures

Regular columnist Robert Marda discusses a few ideas on stored procedure documentation. How much doc...

FORUM

blocking

blocking

SCRIPT

Remove comments from the SQL Code

Takes text (varchar(max)) as input and strips out any comments and RETURN the string. Comment is rep...

Tags
miscellaneous    
t-sql    
 
Contribute

Join the most active online SQL Server Community

SQL knowledge, delivered daily, free:

Email address:  

You make SSC a better place

As a member of SQLServerCentral, you get free access to loads of fresh content: thousands of articles and SQL scripts, a library of free eBooks, a weekly database news roundup, a great Q & A platform… And it’s our huge, buzzing community of SQL Server Professionals that makes it such a success.

Join us!

Steve Jones
Editor, SQLServerCentral.com

Already a member? Jump in:

Email address:   Password:   Remember me: Forgotten your password?
Steve Jones