Comp 15

Commenting Guidelines

Why should I comment my code?

Comment to provide context and to explain why. You might know what your code does, but others (graders, TAs, professors, yourself six months from now) will not. Comments help readers understand your code more quickly. The best code is self-documenting; it is better to choose good variable names that explain themselves than obscure variable names that require comments to explain. However, comments are still necessary to make your code readable. When do I comment my code?

There are two options:

  1. Before writing your code. Use comments (potentially combined with pseudo-code) to plan what you're going to write. As you write your code, update the comments to reflect changes in your plan.
  2. As you write your code. Describe what you're doing in whatever piece of code you're currently writing. As your code becomes hmore complete, you can edit and potentially remove comments.
Writing your comments after finishing your code is not an option! If you show code to a member of the course staff, it is acceptable for them to say “I can't read this code without documentation. I'll help someone else while you work on that. Let me know when the documentation is complete.”

The most important part of commenting is that the comments and code are in-sync with each other. Regardless of when you choose to write your comments, give them a once-over before submitting them to make sure that they still accurately represent your implementation. I have pondered for hours why code seemed to be different from what the comments said, only to conclude eventually that the code was different from what the comments said. Then I had to find out which (if either!) was correct for the problem. Confidence in the code goes down after this.

What types of comments do I need to put in my code?