How many comments are too much comments

edited November 2017 in General

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?

Tagged:

Comments

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

  • //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) {
    
  • Try to avoid negative names for flags because you end up writing statements like

    If not disappeared then...
    
  • edited November 2017

    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);
    }
    
Sign In or Register to comment.