Styles of Source Code Comments in C#, SQL, XML, HTML, CSS, JavaScript

Developers take months to write beautiful pieces of code and reviewer gets only few hours or I say, minutes to provide suggestions and improvisations. Then it becomes a hard deal for a developer to showcase their work. At this moment, comments prove to be a nice packaging which can enhance the visibility of code and also reduce maintenance issues in the long run. There are different commenting styles and guides available on the internet but not under a single package, so this article is the desired wrapping to share a one stop solution of comment styles.

Let's See My Favorite C# First

Single Line Comments or Inline Comments

These comments are most widely used and very useful in explaining the code, in case there is a speed breaker in walkthrough that appears suddenly. These are written as:

//declaring variables
int count=0;
string name=string.empty;

OR while writing a complex or confusing logic which requires step by step explanation.

public void GetProductRatings
{
//Call third party rating service
}

Note: Do not continue to write your code in the same line which contains comments with ‘//’. That will comment your code also and you might spend some of your time in unnecessary debugging.

Multiple Line Comments or Descriptive Block

I always say if something is available for use, then it will be useful, just that frequency of use may vary. There is a big confusion between the use of single line comments and multiple line comments. I would say both are good and require some thought before inserting them in the code file. Let's say, we have a situation where we need to share the full logic of the code, then it would become necessary to use multiple line comments or descriptive block. My personal recommendation is to use only one descriptive block at the top of each page which describes the logic of the page at a single place. These comments are written as:

%***********************************************************************
Page Title: Employee
Author: CodeSpread
Description: This page contains the following logic
1.Extract the information of Employee : GetEmployeeDetails()
2.Enlist all the Employee: GetAllEmployee()
Created Date:
Modified Date:
************************************************************************%

Looks cool!!

XML Comments Feature

The best time saver feature available to a developer. Let's say you wrote a function like:

//put your cursor here to include XML comments
public employee GetEmployeeDetails(int employeeid)
{
//Implementation
}

Just type ‘/’ 3 times where you have put your cursor and voila, you have inserted XML comments with default fields.

/// <summary>
///
/// </summary>
/// <param name="employeeid"></param>
public employee GetEmployeeDetails(int employeeid)
{
//Implementation
}

Customize the comments as per the logic you have written:

/// <summary>
/// Function to extract employee details
/// </summary>
/// <param name="employeeid">employee id to filter the results</param>
public employee GetEmployeeDetails(int employeeid)
{
//Implementation
}

One more advice is to specify region and provide a more concentrated view of the code file. It really helps.

#region Employee Details

/// <summary>
/// Function to extract employee details
/// </summary>
/// <param name="employeeid">employee id to filter the results</param>
public employee GetEmployeeDetails(int employeeid)
{
//Implementation
}
#endregion

SQL Comments

So we move to SQL, here comments are given in either single line or multiline. Both the formats are given below:

Single Line Comments

These are inline comments which begin with ‘- -’ two hyphens and limited to only single line. A word of caution is to take care while including single line comments in the queries, else it can lead to disastrous results. For example:

-- get employee details for employeeid=100
select * from employee where employeeid=100

In the above example, you can see that comments are of similar size like query so just an advice that unnecessary comments or long comments can defeat the purpose of visibility and packaging of code. Please try to avoid such conditions and write compact comments.

Multi line Comments

Similar to C#, in SQL, comments begin with a ‘/*’ and end with ‘*/’. These are mainly used in headers to provide detailed information about the queries.

%****************************************************************************
*Stored procedure getallemployee will return all the employee data.
*Created By: CodeSpread
*Created Date:
*Modified Date:
******************************************************************************%
Create proc getallemployee
AS
select * from employee
Go

XML Comments

There is only one syntax available for XML which is independent of single or multi line feature. It begins with ‘’. Let's see:

<booklist>
<book>
<name>XML</name>
<author>CodeSpread</author>
</book>
<!-- <book>
<name>HTML</name>
<author>CodeSpread</author>
</book>
</booklist>-->

In the above example, the second node for book is commented. I have one recommendation for the XML containing ‘CDATA’ , as the ‘<’ ‘>’ can block the comment syntax so care should be taken while using comments in XML having CDATA. For example:

<booklist>
<book>
<name>XML</name>
<author>CodeSpread</author>
</book>
<!-- <book>
<name>HTML</name>
<author><![CDATA[ CodeSpread]-->;<!--]></author>-->
</book>
</booklist>-->

HTML Comments

Same as XML.

CSS Comments

Comments in CSS are achieved by multi line comments syntax and it begins with ‘/*’ and ends with ‘*/’ .

/**********
.title
{
color:red
}
**********/

JavaScript Comments

There are three types of comments available in JavaScript. Let's see:

Inline Comments

These are one line comments. It begins with ‘//’ and is scoped to the current line.

<script type="text/javascript">
function Hello()
{
//Display Message
alert("Hello World!")
}

</script>

Multi Line Comments

These comments starts with ‘/*’ and ends with ‘*/’ and extends to multiple lines:

/*******
JavaScript to display
‘Hello World’
**********/
<script type="text/javascript">
function Hello()
{
alert("Hello World!")
}
</script>

HTML Comments in JavaScript

HTML Comments ‘’ can also be used to comment JavaScript but the trailing ‘—>’ is not recognized by JavaScript block, so double slashes ‘//’ are used.

<script type="text/javascript">
<!--
function Hello()
{
alert("Hello World!")
}
//-->
</script>

Conclusion

We have tried to identify all the common comment syntax which we use in our daily development. If you would like to contribute to codespread.com, please send a message to admin@codespread.com.
CodeProject

Related Posts

1. UI: Jquery is JavaScript Library
2. Nice reference for C# evolution Part 2
3. SQL:Target a Trigger