Comments in HTML and CSS - Complete, Concrete, Concise

An important part of coding is documenting your code with comments

Introduction to Comments
HTML Comments
CSS Comments
Guidelines for Writing Good Comments
Final Words
References

Introduction to Comments

In a perfect world, code would be self documenting and as you read it from top to bottom you would perfectly understand its structure and behaviour.

In the real world – except for trivial code examples (the kind you fit in a dozen lines or less and can keep in your head) – understanding any significant piece of code takes considerable effort.

Comments are textual information that are added to the code to help document the code. Comments do not affect the behaviour of the code in any way and are ignored when the code is processed. Comments are there to help humans understand the code easier – but only if they are useful and accurate.

HTML Comments

HTML comments begin with . In between those characters, you can have almost any type of text string you like and it can span multiple lines.

<!--This is an HTML comment-->

<!-- While a space is not necessary after
     the opening characters, it does make it
     easier to read and avoid certain problems -->

<!--
  You can also put the comment markers on
  separate lines to make it a little neater.
-->

<!--
  The HTML code inside this comment
  will never be processed.

  <div>
    <div>
      <p>A paragraph inside divs</p>
    </div>
  </div>

-->

The specification has a few rules regarding HTML comments:

the text must not start with the string >,
nor start with the string ->,
nor contain the strings , or --!>, +
nor end with the string <!-

Basically, as long as you don’t try to nest HTML comments inside HTML comments, you will be fine.

<!--
  <!-- Nested comments are bad -->
-->

CSS Comments

CSS comments begin with /* and end with */. In between those characters you can have almost any types of text string you like and it can span multiple lines.

/*This is a CSS comment*/

/* A leading space makes the comment
   easier to read */

/*
   You can also put the comment markers on
   separate lines to make it a little neater.
*/

/*
   The CSS code inside this comment
   will never be processed.

   .my-style {
     font-size: 24px;
     color: green;
     padding: 5px;
     background: orange;
 }

*/

As with HTML comments, you cannot nest CSS comments, so the first */ will always end the comment:

/*
  /* Nested comments are bad */
*/

Guidelines for Writing Good Comments

Comments are written for two types of audience:

Your future self
Others

Your future self (technically speaking) is somebody else because, 6 months or a year or 10 years in the future, you are unlikely to still be in the same frame of mind as when you wrote the code. So everything that was “obvious” when you were writing your code is no longer obvious.

Comments are written for two different purposes:

Documenting (what you are doing)
Clarifying (why you are doing it)

Comments should answer the questions: what and why. The how is answered by the code itself because that is the implementation.

Let’s comment the first HTML program we encountered in this tutorial series:

<!--
  The following is not HTML, it is a document declaration.
  It tells the browser what type of document it is.
  It is case-insensitive. This declaration tells the
  browser that all the code that follows is HTML5 code.
-->
<!DOCTYPE HTML>

<!--
  This is an HTML tag and marks the start of the HTML
  document.

  There is a corresponding closing tag </html>. Most
  HTML tags come in pairs.
-->
<html>

  <!--
     The head section contains metadata (a fancy way of
     saying information) about the document. Things which
     are not part of the content of the document tend to
     go in this section.

     There is a corresponding closing tag </head> which
     marks the end of the head section
  -->
  <head>

    <!--
      The title of the document. Typically appears in
      the browser tab.
    -->
    <title>Hello World</title>

    <!--
      Use UTF-8 character encoding for this page. In
      general, it should always be UTF-8.
    -->
    <meta charset="utf-8"  />

  </head> <!-- The end of the head section -->

  <!--
    The body section contains the content that is
    displayed in the web browser.

    There is a corresponding closing tag </body> which
    marks the end of the body section.
  -->
  <body>

    <!--
      Content is, generally, contained between paragraph
      tags.
    -->
    <p>Hello World!</p>

  </body> <!-- The end of the body section -->
</html> <!-- The end of the HTML document -->

In general, you shouldn’t comment as extensively as I did in the example above – but for a tutorial it is fine.

When you are learning, it is a good idea to comment freely – explain what you are doing and why you are doing it. As your knowledge develops, you will find yourself documenting less and less.

Your comments should document why you are doing something. For example, you might have a requirement for a particular type of webpage, you could embed the webpage description as a comment:

<!-- This is a page with a single column layout that has
     the following general structure:

     Header
     Navbar
     body of articles
     Footer

     The body has a width of 960px and is centered on the
     page.

     Each article in the body is a card which fits the full
     width of the body less 35px padding on the left and
     right side.

     Each card consists of an image with a 16:9 aspect
     ratio, a title with a font-size of 24px, followed
     by a byline at 12px and a published date (also 12px)
     The text content of the card has a font size of 16px.
-->

Of course, this information could be in an external design document instead of the webpage.

The big problem is maintaining the code comments up to date. You have to be diligent to ensure that you update the comments when making changes to the code that don’t do what the comments say.

I recommend you comment freely as you learn to develop. Comment what you have learned:

<!--
  There are two kinds of HTML lists:
  - ordered <ol> and
  - unordered <ul>.

  List can take and attribute called 'reversed' todo
  display the list in reverse order.
-->

<p>Normal list ordering:</p>
<ol>
  <li>Item one</li>
  <li>Item two</li>
  <li>Item three</li>
</ol>

<p>Reversed list ordering:</p>
<ol reversed>
  <li>Item one</li>
  <li>Item two</li>
  <li>Item three</li>
</ol>

Eventually, you will stop writing mundane comments.

You should avoid commenting what is obvious from reading the code because it adds nothing to the information:

.header {
  /* set the background color to blue */
  background-color: blue;
}

But you can document specific requirements:¹

.header {
  background-color: #1DA1F2; /* Twitter blue */
}

One use of comments is to structure your code:

/* Global */


/* Header */


/* Content */


/* Footer */

Unfortunately, your code won’t always cooperate to break down into such nice clear categories.

Final Words

Comment your code freely.
Don’t comment anything that is obvious.
You can explain what you are doing.
You can explain why you are doing something.
Don’t explain how how you are doing something because that is the code itself.
Keep your comments up to date (in general, you should avoid comments that could be rendered obsolete)

References

Read more about Twitter’s brand requirements. Many organizations and companies have very specific rules regarding the use of colours or fonts or any other aspects that are associated with their brand.↩

Contents