Skip to main content
Commonmark migration
Source Link

Your code is missing several very important comments. Some of the comments you do have are lies, others are trivial, yet others don't say what you should be saying.

The most important comment of all

##The most important comment of all (From the perspective of the lawyers)

// Copyright 2015 Eric Irwin. All rights reserved.

This doesn't matter so much in the world of classroom assignments. In the working world, it can matter a lot. Some people elaborate on what rights are reserved. Why? Reserve all rights. Or maybe refer to the license agreement. Keeping it short and simple makes it easier to insert this very important comment.

The most important comments of all

##The most important comments of all (From the perspective of javadoc)

Every class, every function should have a javadoc comment. You do not (you should not!) go overboard. Do not say when you wrote it, or even who wrote it. Write, in plain English (or plain French, or German, or whatever) why the class or function exists.

In the case of a class, say why the class exists, how to use it. Most classes have multiple member functions, multiple data members. An external user who calls those member functions in a random order is most likely to be toast. How member functions need to be sequenced, how they interact with one another: That's the kind of stuff you want to put into that class javadoc comment.

In the case of a function, document what the function does, why it exists -- in plain English. Document the arguments to the function and the return value from the function. In one case (main), that might be blatantly obvious, but a program only has one main. The arguments to main oftentimes are tricky as can be. In this case, you aren't using the arguments -- so say so!

Other missing comments

##Other missing comments YourYour comments show small things but miss the big picture. A perfect example:

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

Much better, in my opinion:

// Play game after game until the user decides to stop.
while (play) {

That outer loop exists so a user can play multiple games. (This was probably a part of the assignment. So say that.) That's the big picture. So game will restart after a win? That's not "big picture". While well-written code can explain itself to some extent, it does not explain the big picture, aka intent or architecture.

End-of-line comments versus full-line comments

##End-of-line comments versus full-line comments MostMost of your comments are end-of-line comments. This style of commenting forces people to be terse; more often than not, overly terse. It also encourages people to comment the obvious (e.g., i++; // increment i). The only thing worse than i++; // increment i is a comment that is inconsistent with the code.

Commenting the obvious with an end-of-line comment is easy, but your code for the most part should be obvious. A comment on the obvious is not needed. Commenting the not so obvious? End-of-line comments typically don't do that very well.

Your code is missing several very important comments. Some of the comments you do have are lies, others are trivial, yet others don't say what you should be saying.

##The most important comment of all (From the perspective of the lawyers)

// Copyright 2015 Eric Irwin. All rights reserved.

This doesn't matter so much in the world of classroom assignments. In the working world, it can matter a lot. Some people elaborate on what rights are reserved. Why? Reserve all rights. Or maybe refer to the license agreement. Keeping it short and simple makes it easier to insert this very important comment.

##The most important comments of all (From the perspective of javadoc)

Every class, every function should have a javadoc comment. You do not (you should not!) go overboard. Do not say when you wrote it, or even who wrote it. Write, in plain English (or plain French, or German, or whatever) why the class or function exists.

In the case of a class, say why the class exists, how to use it. Most classes have multiple member functions, multiple data members. An external user who calls those member functions in a random order is most likely to be toast. How member functions need to be sequenced, how they interact with one another: That's the kind of stuff you want to put into that class javadoc comment.

In the case of a function, document what the function does, why it exists -- in plain English. Document the arguments to the function and the return value from the function. In one case (main), that might be blatantly obvious, but a program only has one main. The arguments to main oftentimes are tricky as can be. In this case, you aren't using the arguments -- so say so!

##Other missing comments Your comments show small things but miss the big picture. A perfect example:

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

Much better, in my opinion:

// Play game after game until the user decides to stop.
while (play) {

That outer loop exists so a user can play multiple games. (This was probably a part of the assignment. So say that.) That's the big picture. So game will restart after a win? That's not "big picture". While well-written code can explain itself to some extent, it does not explain the big picture, aka intent or architecture.

##End-of-line comments versus full-line comments Most of your comments are end-of-line comments. This style of commenting forces people to be terse; more often than not, overly terse. It also encourages people to comment the obvious (e.g., i++; // increment i). The only thing worse than i++; // increment i is a comment that is inconsistent with the code.

Commenting the obvious with an end-of-line comment is easy, but your code for the most part should be obvious. A comment on the obvious is not needed. Commenting the not so obvious? End-of-line comments typically don't do that very well.

Your code is missing several very important comments. Some of the comments you do have are lies, others are trivial, yet others don't say what you should be saying.

The most important comment of all

(From the perspective of the lawyers)

// Copyright 2015 Eric Irwin. All rights reserved.

This doesn't matter so much in the world of classroom assignments. In the working world, it can matter a lot. Some people elaborate on what rights are reserved. Why? Reserve all rights. Or maybe refer to the license agreement. Keeping it short and simple makes it easier to insert this very important comment.

The most important comments of all

(From the perspective of javadoc)

Every class, every function should have a javadoc comment. You do not (you should not!) go overboard. Do not say when you wrote it, or even who wrote it. Write, in plain English (or plain French, or German, or whatever) why the class or function exists.

In the case of a class, say why the class exists, how to use it. Most classes have multiple member functions, multiple data members. An external user who calls those member functions in a random order is most likely to be toast. How member functions need to be sequenced, how they interact with one another: That's the kind of stuff you want to put into that class javadoc comment.

In the case of a function, document what the function does, why it exists -- in plain English. Document the arguments to the function and the return value from the function. In one case (main), that might be blatantly obvious, but a program only has one main. The arguments to main oftentimes are tricky as can be. In this case, you aren't using the arguments -- so say so!

Other missing comments

Your comments show small things but miss the big picture. A perfect example:

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

Much better, in my opinion:

// Play game after game until the user decides to stop.
while (play) {

That outer loop exists so a user can play multiple games. (This was probably a part of the assignment. So say that.) That's the big picture. So game will restart after a win? That's not "big picture". While well-written code can explain itself to some extent, it does not explain the big picture, aka intent or architecture.

End-of-line comments versus full-line comments

Most of your comments are end-of-line comments. This style of commenting forces people to be terse; more often than not, overly terse. It also encourages people to comment the obvious (e.g., i++; // increment i). The only thing worse than i++; // increment i is a comment that is inconsistent with the code.

Commenting the obvious with an end-of-line comment is easy, but your code for the most part should be obvious. A comment on the obvious is not needed. Commenting the not so obvious? End-of-line comments typically don't do that very well.

Source Link
David Hammen
  • 1.1k
  • 6
  • 12

Your code is missing several very important comments. Some of the comments you do have are lies, others are trivial, yet others don't say what you should be saying.

##The most important comment of all (From the perspective of the lawyers)

// Copyright 2015 Eric Irwin. All rights reserved.

This doesn't matter so much in the world of classroom assignments. In the working world, it can matter a lot. Some people elaborate on what rights are reserved. Why? Reserve all rights. Or maybe refer to the license agreement. Keeping it short and simple makes it easier to insert this very important comment.

##The most important comments of all (From the perspective of javadoc)

Every class, every function should have a javadoc comment. You do not (you should not!) go overboard. Do not say when you wrote it, or even who wrote it. Write, in plain English (or plain French, or German, or whatever) why the class or function exists.

In the case of a class, say why the class exists, how to use it. Most classes have multiple member functions, multiple data members. An external user who calls those member functions in a random order is most likely to be toast. How member functions need to be sequenced, how they interact with one another: That's the kind of stuff you want to put into that class javadoc comment.

In the case of a function, document what the function does, why it exists -- in plain English. Document the arguments to the function and the return value from the function. In one case (main), that might be blatantly obvious, but a program only has one main. The arguments to main oftentimes are tricky as can be. In this case, you aren't using the arguments -- so say so!

##Other missing comments Your comments show small things but miss the big picture. A perfect example:

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

Much better, in my opinion:

// Play game after game until the user decides to stop.
while (play) {

That outer loop exists so a user can play multiple games. (This was probably a part of the assignment. So say that.) That's the big picture. So game will restart after a win? That's not "big picture". While well-written code can explain itself to some extent, it does not explain the big picture, aka intent or architecture.

##End-of-line comments versus full-line comments Most of your comments are end-of-line comments. This style of commenting forces people to be terse; more often than not, overly terse. It also encourages people to comment the obvious (e.g., i++; // increment i). The only thing worse than i++; // increment i is a comment that is inconsistent with the code.

Commenting the obvious with an end-of-line comment is easy, but your code for the most part should be obvious. A comment on the obvious is not needed. Commenting the not so obvious? End-of-line comments typically don't do that very well.