Best Practices for Commenting Your Code

  • Ideally you are using your comments to show your work - if there was a part of your code you struggled with and eventually found a solution for, document this! This is useful for evaluation, and useful for your own notetaking as you start to build your coding skill set. Here’s an example:
    • // I was trying to animate the happy faces so that they "swayed" from left to right. When I tried to use a variable to control the left/right offset, I had trouble figuring out how to reverse the direction. I eventually found that using the cos() function allowed me to create an offset that changes direction automatically. It also produced a nice smooth motion effect
  • It is not necessary to leave verbose comments on basic coding structures that we have gone over as major topics in class. For instance, you don’t have to explain what a for loop is, since we learned that in class already. You should instead explain how the for loop is being used, as in this example: 
    // this for loop increments y from 0 to the height of the canvas
// it draws a line every 5 pixels, and changes the hue of the stroke color
// to create a gradient effect
for(let y = 0;y<height;y+=5){
  let hue = map(y,0,height,0,60);
  stroke(hue,100,100);
  strokeWeight(5);
  line(0,y,width,y);
}
}
  • If you are using coding concepts that go beyond the functions and methods we have currently explored in the class, then it is very important to leave verbose comments that express the following things:
    • What were you trying to do that led you to find this new function / method?
    • How did you find this method (web search, p5.js reference, textbook, etc)
    • Provide a link to the source where you learned about this method
    • Explain what each of the components of the snippet are doing, so that you can demonstrate that you’ve taken the time to understand the function or method, rather than just copying and pasting it
    • For example:
    • //I was trying to figure out how to have the sketch resize automatically when the window size changed. I did a Google search and found an example on the p5.js website that accomplishes this, at this URL: https://p5js.org/reference/p5/windowResized/. In this example, a windowResized function is used, which is triggered every time the user resizes the browser. Within the windowResized function, I am using the resizeCanvas function, which modifies the canvas size. I'm using windowWidth and windowHeight as parameters for the resizeCanvas function, so the new canvas size matches the changed window size

  • You should never generate comments using ChatGPT or other LLMs, nor should you ever have ChatGPT or other LLMS augment or translate your comments. It is very obvious when comments are generated or formatted by ChatGPT. Inclusion of any text generated by LLMs in your code will result in failure of the assignment.

  • Here is an example of a p5.js assignment with proper commenting. The resulting sketch site can be viewed here