//STYLE: Add comments to communicate

To truly understand something, you have to teach it...

Programming languages have comments — a way for the programmer to leave notes for humans in the code. Comments are invisible to the computer, and don't do anything.

Except make your code not suck.

Comments are enclosed by codes that are different for each programming language. In our course, we will be using four kinds of comments:

  1. HTML:
    <!-- HTML lets us put multi-line comments inside these... -->
  2. Cascading Style Sheets (CSS):
    /* CSS lets us put multiline comments inside the slash-star */
  3. Javascript (single-line):
    // Javascript let's you add a comment with a double-slash...
  4. Javascript (multi-line):
    /* Javascript also lets you add a comment over
    several lines with slash-star, too. */

The main point of comments is to help explain and structure your code so that it helps you stay organized. It also helps you communicate clearly to any human who may have read your code, including your co-workers, your employer, and even yourself, after enough time has passed.

It is considered unprofessional to create uncommented code. Think of comments as your way to teach others what is going on in your code. Treat the reader like they are a beginning programmer.

Use comments to...

An example of the four kinds of comments

<!doctype html>
<html lang="en">
    <head>
        <meta charset="UTF-8">
        
        <title>Parts of a Web Page</title>
        <meta name="description" content="How to use comments in HTML, CSS, and JS">
        <meta name="author" content="Dave Drapak">

        <!--
            Change log: 
                27. July 2015       - created!
                29. July            - I always use a change log to see how things grow
                                      and change. I often add TODO lists here as well,
                                      and check them off as they are finished.
                11. February 2018   - moved <script> to end of code for good style
        -->

        <style>
            p {
                /* CSS comments go inside here */
                color:  red;
            }
        </style>
    </head>

    <body>
        <!-- show a paragraph -->
        <!-- HTML comments go inside these -->
        <p>Hello there!</p>
		
        <script>
            // MAIN: You should explain what each function does before it is defined
            var mainProcedure = function () {
                /* 
                    In Javascript, you can also have multi-line comments
                */
            }
        </script>
    </body>
</html>

Learn more