It is a very good working practice to comment your code in every language you use. Comments serve two major functions:

As notes and reminders

Comments allow you leave yourself notes as to what sections of code do, and what they are there for. It is common, as both a freelance and full-time developer, to return to code that you have not seen in six months or more: comments allow you to quickly remember what each piece of code does.

As “traffic cones” around code that is problematic.

Code surrounded by comment markup immediately ceases to work. Because code on a web page is read from the top down, you can narrow down the cause of problems by removing sections from execution by means of comments, moving the start and ending comment markup around to analyse problems via a process of elimination.

Content, markup and code within comments does not appear on a web page, but can still be read by anyone what access to your source code. (In HTML, CSS and JavaScript, that is as easy as using View / Source in the browser).

HTML

1. <!-- this is an HTML comment -->

Note that HTML comments are not tags; this can be confusing to many neophyte coders, as they appear to break all the rules of XHTML. Comments may be placed over multiple lines.

1. <!-- this is a comment
2. over multiple lines -->

CSS

1. /* This is a CSS comment */

CSS comments may also be broken over multiple lines:

1. /* p { font-color: black; }
2. hr { color: red; }
3. both of the above lines, plus these two
4. will be ignored */

You will find that some web development text editors and WYSIWYG tools insert HTML comments immediately inside embedded styles and JavaScript in an odd way:

1. <style type=”text/css”>
2. <!--
4. -->
5. </style>

or

1. <script type=”text/javascript”>
2. <!--
4. -->
5. </script>

This is an old trick employed to protect very early browsers that only understood HTML from possible misinterpretation of CSS and JavaScript. The technique is largely irrelevant now, but it does no harm to use it. What is important to remember is that (a) the JavaScript and CSS will still work in compatible browsers (HTML comments only block HTML, not CSS or JavaScript), and (b) you must still use the appropriate JavaScript and CSS comment code once you start writing in those languages.

JavaScript

Comments in JavaScript code are the same as for CSS:

1. /* this is a JavaScript
2. comment */

It is also possible to do single-line JavaScript comments:

1. // this is a single-line JavaScript comment

I don’t recommend the single-line comment format, as it is too easy for an errant carriage return to sneak into a comment and force the remnant into your code, breaking it.

PHP

PHP comments are exactly the same as JavaScript comments:

1. /* this is a PHP
2. comment */
3. // so is this

For the same reasons given in JavaScript comments, I do not recommend the single-line format for PHP comments.