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:

• Put { braces at the end of the line, and indent the containing block 3 spaces. Put the closing } brace on a line by itself, at the indentation level of the outer block.
• Always use braces around logical bodies even when there is only a single statement. (For example, write if (n > 3) { i = 13; }.) This avoids awkward problems when additional statements are inserted.
• Always put a space before a (. An alternate convention it to put a space before all ('s except for method calls. (The text follows this sometimes, but is inconsistent.)
• Put spaces between arithmatic operator tokens.

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:

• Implementation comments (that describe how a particular fragment of code works)
• Interface comments (that describe what a method or class does to a client)
• Annotations (syntax fragments that can be interpreted by a checking tool such as ESC/Java; these are not really comments, but are written like comments so the Java compiler will ignore them)

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.

University of Virginia Department of Computer Science CS 201J: Engineering Software

Sponsored by the National Science Foundation

cs201j-staff@cs.virginia.edu