Processing+-+Comments+Tutorial

=Processing Module – Comments=

You might have noticed that it would be really useful to be able to make notes for yourself right in your code (and you've seen it used in the Khan Academy modules). However, if you add extra text to your program, the computer will get very confused!

Programmers often want to leave notes for themselves or others in their code. This is //essential// when you get more than a few lines of code and it starts to get complicated. Programmers use **comments** to leave notes in their code, for themselves, for other programmers who may look at the code, or in your case, for those who are evaluating (grading!) their code.

There are two ways to leave comments in Processing: Option 1: code format="java" // - two slashes will make everything on that line a comment code

Option 2: code format="java" /* starts a mult-line comment. You can add anything you like

on many

lines and it wil all

be considered a comment until you reach

code

(/* starts the comment and */ closes it)

You Try:
 * 1) Open Module 2 and try adding a single line comment and a multi-line comment. Run your program. If you did it correctly, you shouldn’t see any changes in your program! If you didn’t do it correctly, you’ll probably get an error.

How does this affect you?

You need to get in the habit of adding comments to your code. When you hand in your programs for marking, you must add comments. Specifically, I’ll be looking for these items: -Your name must be at the top of the program, before any code -A brief description should also be at the top, before any code -A description before any complicated bits of code -Additional comments to explain the overall flow of the code

Often, programming students have a hard time understanding what a good amount of commenting is. It //is// possible to have too many comments, although usually the problem is not having enough comments.

Here is an example of too many comments:

code format="java" //Author: Miss Hines

/*This program is designed to draw a box on the screen. The program does this by

drawing 4 lines – the first is from the point (20, 20) to (20, 40), the second is from the point (20, 40) to (40, 40), the third from (40, 40) to (40, 20), and the fourth line is from (40, 20) to (20, 20). The lines are black.



//Set up commands run when the program starts

void setup {

size(400, 400); //makes the sketch 400 px by 400 px

}

//Draw commands will draw a box

void draw {

stroke(0, 0, 0); //makes the lines black

line(20, 20, 20, 40);           //makes the first line from (20, 20) to (20, 40)

line(20, 40, 40, 40);           //makes the second line from (20, 40) to (40, 40)

line(40, 40, 40, 20);           //makes the third line from (40, 40) to (40, 20)

line(40, 20, 20, 20);           //makes the fourth line from (40, 20) to (20, 20)

} code

See how every line is commented? Although these comments are //thorough// they almost make it difficult to read the code. The goals of commenting are: -To make it easier to understand code -To make it easy to find mistakes and bugs in the code -To communicate your intentions and ideas to other programmers who will look at your code -To record important information (such as the author)

Let’s re-visit the program with these ideas in mind:

code format="java" Author: Miss Hines

/*This program is designed to draw a box on the screen between the points (20, 20), (20, 40), (40, 40), and (40, 20).



Set up commands run when the program starts

void setup {

size(400, 400); makes the sketch 400 px by 400 px

}

Draw commands will draw a box as described above

void draw {

stroke(0, 0, 0); //makes the lines black

//draw the box

line(20, 20, 20, 40);

line(20, 40, 40, 40);

line(40, 40, 40, 20);

line(40, 20, 20, 20);

} code

Notice that information that is repeated was taken out. If more shapes were drawn in this manner, you could add a comment that reflects what is happening for each.

Commenting is also known as **inline documentation**. Other types of documentation include **online documentation** (such as web references, tutorials, etc. that are related to the language or program) and **offline documentation.** Offline documentation includes printed materials, such as reference books and printed “cheat sheets.” You can find online documenation and tutorials for Processing at http://processing.org.