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

comment
comment

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

Author: hershey

A passion for knowledge drives me to do programming, A passion for programming drives me to create something different, A passion for creation drives me to spread the knowledge.

Share This Post On

0 Comments

  1. nice superb explaination

    Post a Reply
  2. 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 ?

    Post a Reply

Submit a Comment

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

More from CodeSpread:

  • Java script rendered content is not crawl able.Java script rendered content is not crawl able.There was a requirement to include 'ratings and reviews' plugin on the product pages of our website which is provided by a third party. We included a javascript library and some code as provided by...
  • RegisterStartupScript, RegisterOnSubmitStatementRegisterStartupScript, RegisterOnSubmitStatementWe have discussed RegisterClientScriptBlock, RegisterClientScriptInclude in our previous article here. There are two more methods to client script dynamically from server side. We will discuss thes...
  • RegisterClientScriptBlock, RegisterClientScriptIncludeRegisterClientScriptBlock, RegisterClientScriptInclude"Current trends are more inclined towards the client model for a better UI experience where small pieces of client script are integrated into the application." These client scripts can be declarat...
  • 19 Dec: Must Read Codes [1-5]19 Dec: Must Read Codes [1-5]We are sharing few must read codes/concepts which are required now and then. Each of these codereads doesn't require a full length descriptive article so combining them into groups of five. CodeRe...
  • UI: Jquery is Javascript LibraryUI: Jquery is Javascript LibraryJquery Basics: With the title itself, anybody can deduce that we are indirectly talking about javascript only. So, we can say that Javascipt is the guardian of Jquery. These are client end technol...
  • jQuery: Effects/MethodsjQuery: Effects/MethodsIn our last article, jQuery Part 1 , we covered the basic understanding and now we will move to Methods or effects available in jQuery. Hide/Show/Toggle Methods The most used method Hide/Show. Fr...
  •  SQL Formatting standards – Capitalization, Indentation, Comments, Parenthesis SQL Formatting standards – Capitalization, Indentation, Comments, Parenthesis A post by guest author Milena Petrovic Nobody likes to read a wall of text, even when it’s just plain text. When it comes to reading code, the problem is even bigger. Code can have different for...
  • 24/12/2013: 10 Best Practices of programming from CodeSpread(31-40)24/12/2013: 10 Best Practices of programming from CodeSpread(31-40)We love programming and having a knowledge of best practices always helps in writing beautiful code. We have shared first 20 random best practice in our previous articles 1-10, 11-20, 21-30. More b...