Allan Didier

APCS Detailed Code Commenting

In order for you to be able to demonstrate your understanding of your code, you will need to comment your code. To get credit for your code, your code needs to follow the guidelines in the Programming Grading Rubric and your comments will need to include the following. These comments are basically the questions that I would ask you to explain in person.

  1. Variables
    1. When you create a variable, either the name or comment should explain what purpose it will play in your code. 
    2. Variable names should be descriptive of their purpose. Math calculation and counter variables can be named x, y, and z or i, j, and k.
  2. Methods
    1. At the beginning of each method, explain these three things
      1. What is the general function of the method? 
      2. What are the parameters passed into the method and what are they used for?
      3. What does the method return or do?
    2. All methods need these comments, including constructors, setters, getters, and toString methods generated by Eclipse. 
    3. If a method is overloading or overriding another method make sure to explain that.
      1. Overloading is when you have multiple methods called the same thing but use different parameters. See Game Character Overloaded assignment.
      2. Overriding is when you have a child method called the same thing as a parent method. See Inheritance Intro assignment.
  3. Loops: every “for” and “while” loop
    1. What the loop is doing?
    2. What conditions are met to begin the loop?
    3. What conditions are met to end the loop?
    4. How is the counter variable incremented or when does the conditional variable change value?
  4. Algorithms
    1. Explain chunks of code that perform a certain function. For example:
      1. Battleship program: code that kept a ship from being place out-of-bounds.
      2. Sorting algorithms: code that swaps array variables.
    2. Sorting or searching algorithm,
      1. Explain how the algorithm works in general.
      2. Explain how your code implements the algorithm
  5. Main Program
    1. Many of your main programs are fairly short and/or straightforward.
    2. Comment what each line of your main program is doing if it hasn’t already been commented from something above. 
  6. Special terms
    1. Every time you use the terms “super” or “this”, explain what those terms are doing in that line of code. 
    2. Explain any temporary (temp) or swap variables.