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 proved to be a nice packaging which can enhance the visibility of code and also reduce maintenance issues in long run. There are different commenting styles and guides available on internet but not under a single package so this article is the desired wrapping to share a single stop solution of comment styles.

Lets 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 walk through 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 requires some thought before inserting them in the code file. Lets 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 single place.These comments are written as


%***********************************************************************

Page Title: Employee

Author: CodeSpread

Decription: 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. Lets see 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 ex:


-- get employee details for employeeid=100

select * from employee where employeeid=100

In the above example, you can see that comments is 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 ‘’ .Lets see,


<booklist>

<book>

<name>XML</name>

<author>CodeSpread</author>

</book>

<!-- <book>

<name>HTML</name>

<author>CodeSpread</author>

</book>

</booklist>-->

In the above example, 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 care while using comments in xml having CDATA. For example:


<booklist>

<book>

<name>XML</name>

<author>CodeSpread</author>

</book>

<!-- <book>

<name>HTML</name>

<author><!&#91;CDATA&#91; CodeSpread&#93;-->;<!--&#93;></author>-->

</book>

</booklist>-->

HTML Comments

Same as XML.

CSS Comments

Comments in CSS is 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. Lets see,

  • Inline Comments

These are one line comments.It begins with ‘//’ and 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 are using in our daily development. If you would like to contribute to codespread.com,please send a message to admin@codespread.com

Leave a Reply

Your email address will not be published. Required fields are marked *

  1. thanks for the tutorial
    I am having a problem.
    The feature “Create SQL server database” isn’t available , I can’t select it.
    Can you help, please ?