Guessing a number, but comments concerning

I always get marked down for my comments and I just wanted to see if these comments are acceptable or what I should include/where I should include them.

```
import java.util.*; //so I can use scanner

public class GuessingGame {
public static void main(String[] args) {

Random rand = new Random ();
int max = 100; //sets limit on the random number generator
Scanner input = new Scanner(System.in);
int guess;//so I can compare console input to random number
boolean play = true;
int totalGames = 0;
int totalGuesses = 0;
int bestGame = Integer.MAX_VALUE;

System.out.println("Can you guess the word?");
System.out.println("I am sure you cannot guess!");
System.out.println("Go ahead and try!");
System.out.println();

while (play) { //so game will restart after a win

System.out.println("I'm thinking of a number between 1 and " + max + "...");
int numberToGuess = rand.nextInt(max) + 1;
int numberOfTries = 0;
//so user can continue guessing until correct
boolean win = false;
while (!win) {

System.out.print("Your guess? " + numberToGuess);
guess = input.nextInt();
numberOfTries++;

if (guess == numberToGuess) {
win = true;
} else if (guess > numberToGuess) {
System.out.println("It's lower.");
} else if (guess < numberToGuess) {
System.out.println("It's higher.");
}
input.nextLine();
}

if (numberOfTries == 1) {
System.out.println("You got it right in " + numberOfTries + " guess!");
} else {
System.out.println("You got it right in " + numberOfTries + " guesses!");
}

totalGames++;
totalGuesses+= numberOfTries;
System.out.print("Do you want to play again? ");

//so user can choose to

Welcome to the hell of comments, and personal taste. There are multiple answers to your core question that may be right:

• You have not commented enough.

• You have commented all the wrong things.

• You have commented too much.

• Your comments are in the wrong format.

• You are missing the formal comments.

To be clear though, nothing we can say will be in line with what your marks are based on, unless you can tell us why you were marked down... ;-)

About Comments in general

OK, comments are supposed to make plain what the code does not tell us already.

Let me say that again.

Comments are supposed to make plain what the code does not tell us already.

Now, whether you are marked on that, or not, is a different story. I have found that the academic application of marks for comments is often contrary to the need for comments... particularly when the code is good code.

Good code seldom needs comments.

Let me say that again:

Good code seldom needs comments.

So, follow this logic through, and then follow the inverse back...

• Comments make plain what the code does not tell us already.

• Good code seldom needs comments.

thus....

• Good code seldom needs comments.

• Good code must make plain what the code does without the need for additional explanation.

Applied to your code

Let's start at the top....

import java.util.*; //so I can use scanner

Now, if your code was:

import java.util.Scanner;

then it would not need the comment.

Your next comment is here:

int max = 100; //sets limit on the random number generator

Well, that is, actually, not a horrible comment, or code. But, it could be better, if we gave it a decent name:

int randomGeneratorLimit = 100;

It would be even better if we made that magic number a constant:

private static final int RANDOM_GENERATOR_LIMIT = 100;

Now, no need for a comment at all.

Next up, this line:

while (play) { //so game will restart after a win

Well, this one is interesting.... the comment is actually needed here because of the loop you are using.

If you convert this to a do-while loop, and use some functional extraction... then you can convert your code to a self-documenting, commentless block:

private static boolean playAgain() {
    System.out.print("Do you want to play again? ");
    String answer = input.nextLine();
    char firstLetter = answer.charAt(0);
    return firstLetter == 'y' || firstLetter == 'Y';
}

then you can use that function as follows:

do {

    ....... // game logic

} while (playAgain());

No need for a comment (or a play variable).

Similarly, you have the code:

//so user can continue guessing until correct
     boolean win = false;  
     while (!win) {

This should be a do-while as well, and should look like:

do {
     ..... // game logic
} while (guess != numberToGuess);

Again, that makes the logic clear, no need for a comment.

I believe that has now eliminated all of your comments..... and replaced them with code that does not need a comment, because the code is self-explanatory.

In other news, if you had more functions, with good names, then your code would be simpler to read as well.

Bottom line, though, is that the comments in your code should fill in the blanks that your code does not. In addition, your comments should give details on the motivation, and not the application of your code. You should, in general, comment only on why your code does things, not what your code is doing.

That leads on to the other comments you are missing... JavaDoc.

JavaDoc is documentation that should explain what your code does at an abstract level.

You have no JavaDoc, and you likely should. JavaDoc is where you describe what your code does, because, typically, the people reading the javadoc are not reading the code, so they need something else to tell them what the code does.

StackExchange Code Review Q#90111, answer score: 169