CS 201J 
Engineering Software
Schedule - Problem Sets - Exams - Lectures - Links

CS201J Coding Guidelines

In evaluation CS201J Problem Set submissions, we are looking for more than just a program that "sort of works".

Code for Reading not just Executing

Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live.
John Woods

Good code should be worth reading, not just executing. You should strive to make all your code clear and elegant. Your programs should be written in such a way that someone else can understand them and modify them with expected results. Much of what this course covers involves good ways of designing software to achieve those goals (which are not covered by this document). This document describes many simple and easy things that code authors can do to make their programs more readable.

Descriptive Names

Good names should make it clear to a reader what an identifier means. In most cases, a well-named variable should not need any further explanation in a comment.

It is useful to follow a convention when selecting names so local variables, constants, class names and method names can be quickly distinguished. You may follow whatever convention you choose, so long as you follow it consistently. We recommend following the conventions used in the text (which are similar to those used by the Java API): capitalize names of classes, begin all other names with a lowercase letter, and use mixed case to separate words (likeThisDoes).

Consistent Spacing

Code indentation should reveal the logical structure of a program. It should be easy to line up blocks are the same logical level. For example, the else should be vertically below the corresponding if.

There are various conventions about where spaces and braces should go, and it is not important what you do so long as you follow the same convention consistently throughout the code and it reveals your logical structure clearly. Note however, that when you work with partners on assignments, your conventions should be consistent throughout all the code.

One convention is:

You are encouraged to follow whatever conventions work best for you, so long as they are consistent. In Eclipse, selecting Source | Format will format your code structurally.

Comments about Comments

We will encounter three types of comments in this course: We will cover interface comments and annotations substantially in this course. These comments are essential for enabling others to use your code.

Implementation comments are intended for someone reading your source code. Good code does not need many comments about its implementation. In most cases, clear code should be understandable by itself. You should include comments to describe complex algorithms that may be too hard to deduce from the code itself, to cite sources if you obtained code from another author (of course, make sure it is licensed in a way that allows you to include it), to explain and record changes to code (if you change code after discovering a problem, it is often useful to include the previous code as a comment along with an explanation of the problem and how you fixed it). You should not include gratuitious comments like this:

           i++;  // Add one to i

A bad comment is considerably worse than no comment at all. It wastes the reader's time, or worse misleads the reader to believe something about the code that is not true.

CS201J University of Virginia
Department of Computer Science
CS 201J: Engineering Software
Sponsored by the
National Science Foundation