Comments are a means of communication. They are the notes that a programmer makes to themselves and to any other programmer that may look at their code.

Here are some general commenting suggestions:

• If you have any blocks of logic or sections with multiple conditionals you should have comments with some explanation as to what the code is supposed to do.
• You should also put a comment before each function. This comment should explain what the function does and any arguments / return values. (Exception: If the function is a simple getter/setter in a class then an explanatory comment is not needed.)

  • // Searches for an element in the list and returns its index
    // Returns -1 if elt is null or elt is not in list
    public int indexOf(E elt){ /*code*/ }

• While all variables should be named meaningfully, it may be helpful to add a comment at the initial creation of a variable with further explanation of what it means and when it will be used.

  • int max_x; // variable to contain the largest x coordinate visible on the window

• In higher-level languages it is not necessary to comment everything. We don’t want to clutter up code with unneeded comments such as:

  • int j = 12; //assigning value 12 to variable j
    if ( j <= 0 ) // test to see if j is less than or equal to zero, if so execute the next block of code

• Since comments are meant as a means of communication, they should be relatively free of typos.

While your program is a work in progress, comments are a good place to make notes about what tasks have been completed and what has to be done. If you are trying to resolve a bug you can also keep notes in place about how you have tried to fix it.

Ideally, you comment while you are coding but cleaning up (and perhaps adding) comments is often a good step to take before finalizing a project. The comments should match the current state of the code.