Comments

Memory is short—by writing we preserve It

As programs grow, it becomes harder to remember what each part does and why it was written that way. A comment is a note left in the code for humans to read. CSP ignores comments completely, so they never change what a program does.

Writing a Comment

A comment begins with two forward slashes (//). Everything after the slashes on that line is part of the comment.

Comment (noun)

A section of code for humans only that the language ignores

// This line is a comment and does nothing.
DISPLAY("Hello!")

Only the second line runs here. The first line is skipped entirely.

A comment can also share a line with code. CSP runs the code, then ignores everything after the //.

age ← 10 // the age of the user
DISPLAY(age)

To write a comment that spans multiple lines, start each line with its own //.

// This program stores a name
// and then displays it back.
name ← "Ada"
DISPLAY(name)

Slashes inside a string are just text, not a comment. DISPLAY("a // b") displays a // b.

Using Comments Well

Good comments explain why the code does something, not just what it does. The code already says what it does. Compare these two comments.

// Set total to 0
total ← 0

// Start the total at 0 so we can add each score to it
total ← 0

The first comment only repeats the code. The second tells the reader something new.

Comments are also useful for temporarily disabling a line of code without deleting it. This is called commenting out code.

DISPLAY("This line runs.")
// DISPLAY("This line is skipped.")

Remove the // and the line runs again.

Comments in Other Languages

Not all languages use \\ to denote comments. See below for some various comment types.

# This is a 1 line comment

"""
This is a multi line
doc string comment
"""

// Single line comment

/* This is a multi
line comment */

! Here comments are started by a bang (!)

Next: Conditionals