Java Style Guide

This is a short guide to the code style expected for this course.

Every major software endeavor eventually develops style guidelines; this is true for everything from open-source projects to giant corporate codebases. The pragmatic purpose of good style is so that code written by one person is comprehensible to other people working with that code. When code across an entire project, written by many developers, shares a consistent style, then any developer can dive into the code at any spot and have a fair chance of understanding it. This is a really remarkable feeling as a developer (one I hope you will get to experience later in your career), and the opposite (inconsistent style across a codebase) is a nightmare I hope you'll dodge.

Interestingly enough, even if you're just working on code for yourself, having a consistent style benefits you too: the future you is a completely different person. In a few months or years, you'll have forgotten all the particulars of a given project you worked on, but if you wrote your code to be comprehensible to anyone, this will include future-you. And trust me, future-you will be grateful, because they're going to want to pillage ideas from your code!

In fact, in a few hours your memory of your work will be a little cloudy. Maintaining good style makes debugging much easier, because it's a way to guide two-hours-in-the-future-you through the code that you wrote. So this is also implicitly a basic guide to good software-development practice.

All this motivates the existence of this style guide. To motivate you to follow it, your code in CS 201 will be graded on style. This guide is an explanation of what we will be looking for when we grade.

This style guide is strongly inspired by Google's style requirements for Java and C++. You can check out those links for way more detailed guidelines and deeper discussion of the reasoning behind them.

A Caveat

The fundamental rule of any style guide is that clarity is the goal. If you encounter an isolated situation in which breaking a particular guideline serves to make your code more easily comprehensible, then go ahead and do it. But think critically about whether it's necessary to break the guideline, or if you can do something different to accomplish your goal in a style-conforming way.

The most basic element of code style is formatting. Here are the requirements for our course.

• Indentation — indent code blocks with 4 spaces.
  • Never use tab characters in your code. Don't mix tabs and spaces.
• Line length — no line should exceed 80 character-widths in length, including leading whitespace.
  • If you have an expression that is too long, split it over multiple lines. Continued lines of code should either be indented by 4 or 8 spaces, or indented more to align with similar structure in the line above.

  • If the argument list for a method call or method signature runs over the line length, wrap it so that the left edge of the wrapped lines falls on the right side of the open-paren, like so:

    int useful_value = computeAUsefulValueFromABunchOfNumbers(first_prelim_value,
                                                              second_prelim_value,
                                                              third_prelim_value);
    

    (Note that these are intentionally terrible method and variable names. More on naming later.)

    If this left edge doesn't leave enough room (between it and the 80-character right margin) for long argument names, you may wrap those as above (indented just 4 or 8 characters, rather than all the way to the paren).

  • When wrapping lines, put the line break after binary operators, commas, or open-parens.
  • One exception to the line-length requirement is if you have a long URL in a comment. In this case, it's fine for it to go beyond 80 characters.

• Curly braces — open-curly braces should go at the end of the same line that contains the signature for the code block that they denote, separated from the signature by a space. Close-curly braces should be the first non-whitespace character in their line, indented at the same level as the signature of the block that they end. For example:

  public class StyleExample {
      public static void printAdvice() {
          for(int i = 0; i < 10000; i++) {
              System.out.println("Don't put open-braces on their own lines!");
          }
          System.out.println("Close-braces are indented at the enclosing level.");
      }
  }
  

  • The keyword else may follow a close-curly-brace on the same line, separated by a space. For example:

    if(a) {
        System.out.println("A!");
    } else if(b) {
        System.out.println("B, but not A!");
    } else {
        System.out.println("Neither A nor B");
    }
    

  • Always use curly braces around method or flow-control bodies, even if they're optional.
• Whitespace — use standard typographical rules for whitespace around most punctuation:
  • Do not use whitespace before a comma or semicolon. Do use whitespace after a comma or semicolon, except at the end of the line.
  • Use a single whitespace on either side of binary operators: assignment (=, +=, etc.), comparisons (==, <, !=, etc.), boolean operators (&&, ||, etc.), arithmetic operators (+, /, etc.), and :.
    • If you're writing a long arithmetic or logical expression, you may elide the whitespace around certain operators if it helps clarity. For example, I often get rid of the spaces around * when writing polynomials, because it emphasizes the connection between a monomial term and its coefficient.
  • Do not use whitespace between unary operators and their operands: these include - (as negation), !, ++, etc.
  • Do not use whitespace immediately inside parentheses, square brackets, or curly braces.
  • Do not separate a flow-control keyword (like if or for) from the open-paren that begins its control statements. Similarly, do not separate a method name (either for definition or invocation) from the open-paren that begins its argument list.
  • The above whitespace rules are demonstrated in the following example:

    int j = 0;
    for(int i = 0; i < 100; i++) {
        j += compute(i + 36, i - 36);
        if(!(i % 13 == 0) && (i % 3 == 1)) {
            j = -j;
        }
    }
    

• Blank lines — use blank lines sparingly to enhance readability.
  • Avoid blank lines at the beginning and end of method or flow-control bodies.
  • Leave one blank line between methods. You may also leave two blank lines occasionally to put methods in conceptual groups. Leave at most one line blank at the top of a class declaration, before the first method or data member.
• Repeated structure — if a long statement has some kind of pattern to its structure, you may creatively bend the formatting rules above to support readability and emphasize the structure. This commonly happens in very mathematical code or code that handles complicated conditionals. For example, the following snippet is fine (but probably not the sort of code you'll write in this class):

  double y = d_xx * x*x  +  2.0*d_xy * x*y  +  2.0*d_xz * x*z +
                                d_yy * y*y  +  2.0*d_yz * y*z +
                                                   d_zz * z*z;
  

The essential rule of commenting is this: assume your reader knows the language better than you, but has no idea what you're trying to accomplish. Communicate the meaning of your code, not the mechanics.

• Comments are prose — write every comment in complete sentences, with proper capitalization, grammar, and punctuation. Always include the ending punctuation. Be as concise as possible without sacrificing clarity or proper prose style.
• Verb tense — comments on methods should be in the third-person, non-imperative, present tense, describing the behavior of the method. (For example, “Detects a cycle in the graph, if there is one in start_node's connected component, and returns the IDs of the nodes on that cycle”. Note that we say “Detects”, not “Detect”; “returns”, not “return”.) All other comments should be in present tense, written as though you were walking your reader through the execution of the program. The “royal we” is acceptable for this. So you may say things like, “At this point, we know that A is false, so we have to check B”.
• Comment on the preceding line — when you write a comment about something, put it on the line(s) before the thing you're commenting on, indented to the same level as that thing.
  • One sorta-kinda exception to this rule is commenting the body of an if or else statement — in this case, the comment belongs below the if (or else) line, inside the body, above the contents of the body, and indented at the level of the body. This comment may still describe what the meaning of the condition that puts the program into this body, even though that's technically on the line above the comment.
• Avoid end-of-line comments — one corollary to the above (and also to the 80-character line-length limit) is that you should generally not put inline comments on the same line as the thing they describe. Instead, put them on their own lines, just above each described thing.
• Javadocs — put a Javadoc comment (which begins with /** and ends with */ before every class signature, method signature, and public data member. Use it to describe the effects or purpose of the thing being commented, not its internal workings — you are addressing an outside user in Javadoc comments.
  • Indent the /** at the same level as the signature of the thing that the comment is describing. Indent each line of the comment to at least that level as well.
  • The first sentence of a Javadoc should fit on the first line of the comment.
  • It's mostly up to you how you'd like to format your Javadocs, but be consistent throughout your code. Some people like to start the first line immediately after the /**; some people like to start on the next line. Some people like to put the */ at the end of the last line; others put it on its own line. Some people prepend * at the beginning of each line (so that there's a solid column of stars along the left edge of the Javadoc); others just indent each line to match the opening /**. You can choose how you'd like to do it.
  • One-line Javadocs are acceptable: that is, you can have the /**, the single-line text of your comment, and the */ all on the same line, if they'll fit.
  • Do not put HTML code in your Javadoc comments. (Note that this rule is contrary to the recommended style from the Java designers: the default Javadoc parser requires HTML for formatting. However, this completely breaks the idea that comments are made for humans to read, not machines, so our style guide departs strongly from “standard practice” in this case.)
  • See the official Javadoc guide for more details.
• Conceptual code segments — write a comment before each conceptually-coherent chunk of code. If you have a long method with, say, three high-level steps in its logic, write a comment describing each step above the chunk of code the implements that step.
• Avoid commenting individual lines — you should only very rarely need a comment to explain what a single line of code does (unless it's a standalone step in a multi-step process, as described in the previous rule). If your code is so complicated that it's unclear what a single line does, consider redesigning it so it's easier to understand. And remember, your comments should describe meaning, not mechanics, so the following kind of comment is to be avoided:

  // Call getNewNumber() on b and save it in a.
  a = getNewNumber(b);
  

• Commented-out debugging code — it can be useful to leave in limited amounts of debugging code that you have commented out. If you had to add debugging statements to some portion of your code, then after you've figured out what's going on, you should add an explanatory comment summarizing the situation. At this point, it's usually fine to completely remove the debugging statements. But sometimes leaving them in, but commented out, can serve as a useful guide to a new reader trying to follow your explanation. Regardless of your choice, make sure that your comments do not distract from your reader's ability to follow your code.

The names you choose for classes, methods, and variables ought to act like comments in their own right: they should make it easier for an outsider to understand the meaning and intention of your code, just by looking at variable names.

• Meaningful names — names should describe meaning, not mechanics. Use your variable and method names to describe the purpose or meaning of the thing named.
  • Do not include type information in the names of variables (that is, the word “dictionary” should not appear in the name of a variable that happens to be of a Dictionary type; nor should any abbreviation like “dict”).
• No special names for data members — you don't need to (and should not) put any sort of special prefix or suffix on the names of class data members. (Some coding conventions put “my” at the beginning or an underscore at the end, but the Java community generally avoids this.)
• Avoid abbreviations — avoid abbreviations in variable and method names.
  • A handful of common code abbreviations have become more or less standardized and are therefore acceptable: “num”, “cnt”, “len”, “sz”, “idx”, “max”, etc. (for, respectively, “number”, “count”, “length”, “size”, “index”, “maximum”, ...).
• Be as concise as possible, and no more concise — long variable, type, and method names can be unwieldy, but especially in the Java community, clarity is valued over conciseness. Generally speaking, if your name looks like a little sentence unto itself, you can probably cut it down a little.
• Methods are verbs — method names should be imperative, present-tense, third-person verb phrases, like “printSummary()” or “ensureCapacity()”. Note that this does not mean they have to be very long; one to four words is usually enough.
  • Some short method names are so common that they are standard exceptions to this rule: length(), size(), num___(), etc.
  • One additional exception is that methods returning boolean often begin with “is”; e.g., isEmpty().
• Formatting — use capitalized camel-case for ClassNames, lowercase camel-case for methodNames, all-lowercase with underscores for variable_names, and all-caps with underscores for CONSTANT_NAMES. If you happen to create a name that includes an acronym, treat the acronym as though it were all-lowercase by default (that is, capitalize the first letter if the acronym appears as part of a class name, but not if it's part of a variable name).