How many comments are too much comments

schotsl

I'm starting a bigger project and wanted to make sure it would be understandable, so I started adding comments but I feel like I'm way over doing it after looking around a bit.

Here's a snippet

//This is the start scene.
void sceneZero() {
  boolean returnButtonDisappeared = true;
  boolean usernameBoxDisappeared = true;

  //If the previous scene was the menu scene.
  if (previousScene == 3) {
    //The booleans will be set to false if the objects haven't disappeared.
    returnButtonDisappeared = returnButtonDisappear();
    usernameBoxDisappeared = usernameBoxDisappear(); 

    //If either of the objects haven't disappeared keep drawing that object.
    if (!returnButtonDisappeared) returnButton();
    if (!usernameBoxDisappeared) usernameBox();
  }

  //If both the objects have disappeared draw the new objects and make them appear.
  if (usernameBoxDisappeared && returnButtonDisappeared) {
    specialThanksAppear();
    pressHereAppear();

    specialThanks();
    pressHere();
  }
}

Or is this a normal amount of comments?

quark

How long is a piece of string?

There is no correct answer. Your comments should explain what the program does so that you can maintain the source code. If you come back to your code after a six month absence and understand it, then you have enough comments.

GoToLoop

//If the previous scene was the menu scene.
if (previousScene == 3) {

The comment above becomes unecessary by defining state constants: *-:)

static final int MENU = 3;
int previousScene;

// ...

if (previousScene == MENU) {

koogs

Try to avoid negative names for flags because you end up writing statements like

If not disappeared then...

jeremydouglass

When in doubt, add comments.

Good variable naming can make some comments redundant -- it is obvious what is happening from the code. This might need multiple comments:

boolean state;
...
// if the device is on
if(state){
  // turn it red
  update(255,0,0);
}

vs. this doesn't need any comments:

boolean isOn;
color red = color(255,0,0);
...
if(isOn) {
  setColor(red);
}

You can also use functions and methods to make code more readable without comments. This code might need every line explained:

// detect mouse pressed in upper left quadrant of the screen
if(mouseX < width/2 && mouseY < height/2 && mousePressed) {
  // draw a smiley face
  ellipseMode(CENTER);
  ellipse(25,25,25,25);
  ellipse(75,25,25,25);
  arc(50, 50, 80, 80, 0, PI, PIE);
}

vs. this, with function names doing the labeling, and making the code itself concise and easy to read:

if( upperLeftPress() ){
  drawSmileyFace();
}
...
boolean upperLeftPress(){
  return(mouseX < width/2 && mouseY < height/2 && mousePressed);
}
void drawSmileyFace(){
  ellipseMode(CENTER);
  ellipse(25,25,25,25);
  ellipse(75,25,25,25);
  arc(50, 50, 80, 80, 0, PI, PIE);
}