Return to Revisions

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

1. you have not commented enough
2. you have commented all the wrong things
3. you have commented too much.
4. your comments are in the wrong format
5. 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... ;-)

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...

1. comments make plain what the code does not tell us already
2. good code seldom needs comments

thus....

1. good code seldom needs comments
2. good code must make plain what the code does without the need for additional explanation.

how is this 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, ingeneral, 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 likelye 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.