Readability Review

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.

Overview

The readability review you will receive in this course focuses on two main aspects of writing readable code.

• Checking that you follow Java conventions.

  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.

• Checking that you provide sufficient information to the reader.

  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.

Reviews

Below, we describe in more detail the particular elements that we will check for.

Naming

• Follow the Java naming conventions.

  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.

• Names should be informative.

  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.

Formatting

• Follow the usual Java conventions for whitespace in expressions. For example:
  • Binary operators like + should normally have a space before and after them. (You can skip the space on unary operators like !.)
  • Keywords like if, for, and assert should be followed by a space.
  • Curly braces ({) at the end of a line should be preceded by a space. Those at the beginning of a line (}) should be followed by a space if there is more code on that line (e.g., } else {).
  • The : in a for-each loop should be surrounded by spaces.
  • A comma (,) should be followed by a space but not preceed by one.

• Do not use unnecessary parentheses (unless they clear up potential confusion). For example:
  • The outer parentheses are unnecessary in !(foo.isEmpty()).
  • The parentheses are unnecessary in assert (foo != null);

• Lines should not be longer than 100 characters.

• Method bodies should be broken into bite-size paragraphs.

  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.)

Indenting

• Indentation should be consistent and match the code structure.

  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.

Commenting

• Comments should be informative.

  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.

• Provide sufficient information in the comments that the reader does not need to think hard in order to understand your code.

  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.

  • All classes and methods should have some sort of Javadoc comment. 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.
  • Method bodies should contain // inline comments explaining what the code does. 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 good understanding of how the method works.