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.
