Java Programming Style Guide

Commenting Conventions

Comments provide readers with the information helpful to understanding your program. Your CS 110 comments will be greatly abbreviated compared to the types of comments recommended for real-world programs.

Use comments to provide overviews or summaries of chunks of code and to provide additional information that is not readily available in the code itself.

Comment the details of nontrivial or non obvious design decisions; avoid comments that merely duplicate information that is present in and clear from reading the code.

We will use three types of comments with CS 110 programs:

Avoid over-commenting your code. The frequency of comments sometimes reflects poor quality of code. When you feel compelled to add a comment, consider rewriting the code to make it clearer.

In addition, the C style comments /* ... */ may be used temporarily for commenting out blocks of code during debugging. Programs submitted for a grade should not have blocks of code commented out however. Either fix the code or remove it from the program.