Introduction
Learning to read and understand source code is an important skill that takes
some time and practice to develop. It is important
- to help understand how other people have solved problems by reading their code;
- for correctly adapting other people's code for your own uses;
- for modifying and extending your own code as needed.
However, even trying to understand your own code after being away from it
for some months may be quite challenging. As your facility with a language
improves, so will your ability to read code. Even a skilled reader will find
reading large amounts of code without the aid of some form of documentation or
descriptive text can still be very time consuming and difficult - even painful.
There are a number of things you should do to make understanding your code
easier. These include using descriptive variable names, formatting code so it
is easier to read, and documenting what you have done. JavaScript, like other
languages, provides a way to include documentation interspersed with JavaScript
code to make the code easier to understand without interfering with the
execution of the script.
Comments
Comments are notes, usually written by the authors of a script, that
documents how the script works, how it can be used, and other information the
writers of the script thought important to note. Comments are text that is not
interpreted by the JavaScript interpreter. To exclude comments from being
interpreted, they must be preceded by special characters or enclosed in special
characters.
//Single
Line Comments
Two forward slashes
//
begin a comment that begins with the //
and goes to the end of the line. For example://Global Variables for the Quiz
var maxQuestions = 12 //Change this value if you want to allow more questions.
var firstQuestion = 0 //Change this to any number from 0 to (maxQuestions - 1).
//Do Not edit code from this point on!
/*Multiline
or Bracketed Comments*/
The
/* and */ characters can be used to enclose a
comment. Here are some examples:/* Global Variables for Quiz */
var maxQuestions = 12 /*Change this value if you want to allow more questions.*/
var firstQuestion = 0 /*Change this to to any number from 0 to one less than maxQuestions.*/
/* Do Not edit code from this point on! */
/**
* The checkAnswer(choice) method is called when the user selects an answer
* from a list of radio buttons. If the answer is correct the method returns
* true. If not it returns false. The method keeps track of the number of
* user guesses by incrementing a counter in the question object.
* The function expects one numeric parameter to be passed to it.
**/
function checkAnswer(choice){
this.guesses++
if (choice == this.answer)
return true
else
return false
}
While developing a script, comments are often left to the end to add to a
source file. This is an unfortunate practice as it increases the probability
that few comments will ever be added to a script as it nears completion. Adding
comments as the script progresses is a good practice - perhaps something like
cleaning while you cook - the comments will be more complete and writing them
may help in clarifying what was being attempted as the work progresses.
Comments are particularly essential for scripts where numerous sections of code
must work together and where more complex tasks are being performed.
