Background

About a year ago, I posted a question on Instagram. Do you have your students comment on their code? The answer was a resounding “YES!” and I completely agree with this answer. Commenting code is highly important for both the programmer and the reader of the code. 

The Programmer’s Perspective on Commenting

I’ve been programming for almost 10 years now. If I wanted to go back and review my code from my undergraduate days, I could. However, I know that I would not remember what each program did, so how valuable is that code? … I’m not sure. I know that I didn’t comment it well and it would take time to decode it. If I had commented on any part of it, the process of remembering would go so much faster. So, from the programmer perspective, it is helpful to comment so that you can remember what the code does when you need to reference it later. 

A part of the AP® curriculum is to know what pre- and post-conditions are. A precondition is something that needs to be true before the program/method/function can run. A postcondition is something that is true after the piece of code runs. I think that it is beneficial to put comments before each method or function to remind yourself what conditions will be true. 

The Reader’s Perspective on Commenting

I’ve been teaching computer science for about 5 years now and reading students’ code is part of my job. We do some complicated methods sometimes, and it helps when the students put comments above the method, so that I know what the outcome of that method is supposed to be. 

Having comments on code also helps with grading. If they say it’s supposed to do something, and it doesn’t do that, then I know how to grade it. 

From a real-world perspective, several people may work on a project and they each may add to the overall code. When trying to interweave the code back together, I think that it would be beneficial to have some sort of commenting on each piece. This would allow the programmers to put the code back together pretty fast. 

How much commenting is too much?

I think there is happy-medium to how many comments should be in a piece of code. Too little and no one knows what the code is doing – too much and it is distracting to reading the code. 

For the AP® CS A Test

While I completely agree with commenting code, I think I remember hearing a Summer Institute teacher saying that the comments on the FRQs are unnecessary. The goal of the AP® test is to determine whether or not a student knows the material. They are not worried about commenting. 

For the AP® CS P Test

On the Create portion of the AP® CS Principles test, it is required that one give credit to anyone who wrote code segments to make the code function. The code could be from their partner or if they found it online. Also, any graphics or music must be cited. Comments are a great way to give credit. 

What are your thoughts?

I would love to know what you do in your classroom. Please comment below! 

THIS PRODUCT IS NOT ENDORSED BY AP® OR COLLEGE BOARD.