Writing code that is easy to read is a critical step for producing high quality software. Code that is hard to read is difficult to reason about (both for yourself and your code reviewers), which makes it more likely that bugs will escape detection and affect users. Code that is hard to read is also difficult to change (since it is hard to understand), which makes it more difficult to add new features that users want or even to fix bugs in the code without introducing more bugs.
Part of your grading in the coding assignments will focus on the readability of the code you write. This includes two key parts:
Java programmers have certain expectations about how code will be written. Not adhering to these conventions, while not incorrect, will limit the speed with which others can read your code. Each time the reader encounters an unfamiliar style, they will be forced to slow down while they verify that the oddities in the style do not harm correctness.
Reading someone else's code should be much easier than writing it in the first place, but that will only be true if you pass along the insights that you had while writing it to them — usually in the form of comments. If you do not provide that information, you are asking the reader to rediscover it on their own, making reading your code a much more difficult endeavor.
The following sections provide detailed rules to follow, most of which follow from the two points mentioned above.
For example, all names (with one exception) should use CamelCaps rather than underscores (_) to separate words. Class and interface names should start with a capital letter, while all other names start with lower case. The one exception to the above rules are constants (static final fields) whose names are written in ALL_CAPS, using underscores to separate words.
While you can also use comments to give the reader complete information about what data is stored in a variable, you can do this with even less effort by choosing a good name. In general, the larger the scope of the variable (i.e., the amount of code in which that name can be used), the larger and more informative the name should be. Short, generic names are fine for variables that are only used over a handfull of lines, but variables used over larger scopes should describe their meaning in more detail.
Just like when writing prose, you want to give the reader breaks when reading the code of a method body. Group a handful of lines of code (usually less than 6-8) that share a common purpose into a single paragraph. Write a comment above the paragraph that explains what those lines do. (See below "commenting" below for more on that.)
While we will not force you to use any particular style regarding indentation (e.g., 4 spaces versus 2), your indentation style needs to be consistent throughout the code. More importantly, the indentation needs to match the grammatical structure of the code: all statements in the same block (that are not nested inside a deeper block), should be indented exactly the same way.
While not worse than having no comments, comments that provide no useful information beyond what is easily discernable from the code are likely to annoy the reader. Don't write // close the reader on top of the line reader.close(). You can assume that the reader understands that the code does that.
It is easy to forget that you are an expert on your code but the reader is not. Don't make them repeat the same analysis that you did in order to figure out what the code should do. Tell the reader, in the comments, what your code does. Then the reader's only job is to confirm that the code does what you say it should.
Even ignoring things like @requires that we ask you to write in this class, every method and class should have some comment that describes it's purpose at a high level. A well-chosen name for the class or method might communicate most of this, but you should write out at least a one sentence description just in case the name does not say it all.
Unless the code in the paragraph is extremely obvious, each paragraph should have a comment above it explaining what the code in that paragraph does. Ideally, the reader would be able to look through the comments on each paragraph, ignoring the code completely, and come away with a basic understanding of how the method works.
Do not declare as a class member a variable that could be local to a method. If a variable is needed only in the body of a for loop, declare it within that loop body, not outside.
Wildcards are fine, but do not leave out generic parameters (creating a so-called "raw" type).
Type casts take away the compiler's ability to check correctness, increasing the chances that bugs will sneak through.