describing the code - looking for feedback

Hi highlandcow,

What a great question. The truth is, IMHO, commenting should be simple English that explains what is the overall goal/objective. Your method name and variables should be self documenting, meaning, their name should explain their specific purpose. Confused? No problem, let me answer using the example code you posted; below the code is my explanation.

/* Guessing game where the user has to guess the system generated number. Game ends when user guesses the correct number. Method returns the number of guesses made by the user. */ NOTE: This above comment would be placed on the method running all of this code

// Retrieve a random number between 0 and 10 var randomNumber = getRandomNumber(10);

/* Capture user guesses. This information is needed once the user completes the game. */ var guess; // Create variable "guess". var noOfUserGuessCnt = 0; var isUserGuessCorrect = false;

/* Return a random number, from 0 up to the value of highestNumber */ function getRandomNumber ( highestNumber ) { var num = Math.floor(Math.random() * highestNumber) + 1; return num; } NOTE: The getRandomNumber method shouldn't be here. It should be in it's own block of code, which serves a specific function (i.e. that is, it returns a number in the desired range).

When I read code comments, even my own, I want to understand what's "going on." I know that var {variableName} means I've created a new object. This fact is not important; what is important is WHY did I create that variable. For example, noOfUserGuessCnt; it's easier to understand that this is the number of guesses made by the user. The real question is why is that important? The comment above all the "set up variables" explains it; this information is needed when the game is completed (i.e. set up variables are guess, noOfUserGuessCnt, and isUserGuessCorrect).

There is no wrong answer, to include what you posted. The goal is that when you, or someone else, reviews the code, he/she understands what's going on. I will say that I would encourage responsible use of comments. Putting too much comments is almost as bad as having none at all. The code naming scheme is the most important lesson to take from this exercise. You'll find that your code is much easier to read, if your variable and method names are self explanatory, assisted by easy-to-understand comments. The exercise of good commenting skills will come easier with the more code you write.

HTH

This is my way of commenting <blockquote>

var randomNumber = getRandomNumber(10);
/* created a variable called 'randomNumber' and assigned its value to the function call 'getRandomNumber' and passed in 10 as the parameter */

var guess; // Created the variable "guess".

var guessCount = 0; //Created a  variable called "guessCount" and assigned its value to 0.  

var correctGuess = false; //Created a variable called 'correctGuess' and set its value to false.

function getRandomNumber ( upper ) {
  var num = Math.floor(Math.random() * upper) + 1; 
  return num;
} 
/* Created a function called 'getRandomNumber' and it takes in a value as its parameter. Inside the function we created a variable called num and assigned its value to a random number between 1 and the number we specify when calling the function. After generating the random number we return it.  */

</blockquote> If i managed to help, mark my answer as the best