Tutorial: Commenting Code

How to write notes to remind ourselves of what code does.

Comments

Since computer code can be esoteric, programmers sometimes write notes to help sort out what a piece of code does. We do this using comments in two ways: an 1) end-of-line comment and a 2) multiline comment.

End-of-line comments

An end-of-line comment tells the computer to ignore any text after the comment indicator. We can also put an end-of-line comment on its own line. For an end-of-line comment, we start with two forward slashes, like so:

// This is a comment.

Anything after the slashes will be ignored by the compiler.

Multiline Comments

A multiline comment can include many lines. To insert a multiline comment, we start with a forward slash and an asterisk and end with an asterisk and a forward slash. Here is an example:

/* This is
 a comment. */

Quorum will ignore any text between the beginning of the comment and the end of the comment, even if it spans multiple lines.

Uses of Comments

In addition to explaining code, comments can serve other purposes. One such purpose is temporarily turning off code for testing. For instance, suppose we wrote the following code:

class Main
   action Main
       integer i = 15
       integer j = 25
       integer k = 35
       output i 
       output j 
       output k 
   end
end

Here is an example of commenting out a few lines of code:

class Main
   action Main
       integer i = 15
       //integer j = 25
       //integer k = 35
       output i
   end
end

or with a multiline comment:

class Main
   action Main
       integer i = 15
       /*integer j = 25
       integer k = 35*/
       output i
   end
end

This way, the compiler won't see the code but it will still be in our file. Below is a development environment where we can try out comments. Now, these comments will obviously not do anything, but the point is to try them out to practice how it works.

Next Tutorial

In the next tutorial, we will discuss Assignment 2.3, which describes how work Audio Racing in Quorum..