CS 201: Data Structures (Spring 2018)

Java Programming Style Guide

Good programming style makes your code much more readable and maintainable. Here are some basic style directives that I expect you to follow in your code.

  1. Line up braces. The textbook uses method (a), which is what I usually use. Many programmers prefer method (b). Either method is equally acceptable. Consistency is the key here: pick one and stick with it.

    Method (a) Method (b) 
    if (a == b)
{
   c = d;
   e = f;
}

    if (a == b) {
   c = d;
   e = f;
}

  2. Use whitespace in a meaningful way to make your code readable.

    • Use spaces to indicate the level of nesting. The amount of space you use for each tab is up to you, but you should be consistent. The textbook uses 3 spaces, which is what I will use.
    • Separate related sections of code from unrelated sections of code by the use of blank lines. Do not add too many blank lines.
    • Break up lines that are longer than 80 characters. This makes your code much easier to read when printed and when listed in a standard terminal window.

  3. Comment sections of code that need it. You should use comments to describe a particular twist that might be hard to understand, or to explain what a section of code is doing. If your program has no explanatory comments, you're assuming your readers are more capable than they are.

  4. Use capitalization and descriptive names to make your identifiers clear.

    • Variable and method names should start with a lower case letter. Capital letters should be used to separate multiple words.

      Examples: name, age, personName, getAge

    • Class names should start with a capital letter. Capital letters should be used to separate multiple words.

      Examples: class Person, class Gradebook, class BlackjackGame

    • Constants (public static final) should be in all capital letters. Underscores should be used to separate multiple words.

      Examples: MAX_CAPACITY, DIME_VALUE

  5. Declare your variables with appropriate access.

    • Variables should nearly always be declared private.
    • Methods should be public if they are to be accessed from outside of the class. Otherwise, they should be private (or protected).

  6. Keep your methods short. A method should not be longer than 1–2 screens without good reasons.

  7. Each class header should contain documentation containing

    • Author(s)
    • Description of purpose
    • Known bugs

    You may use Javadoc to accomplish this, and I encourage you to do so.

  8. Each method should contain header documentation containing

    • Author(s) (if not all are same as for class)
    • Description of purpose
    • Description of parameters and return value
    • Citations indicating ideas or code borrowed from other people / sources

    You may use Javadoc to accomplish this, and I encourage you to do so.

  9. Your code should be direct and minimal to get the job done. Don't use five variables and three loops when three variables and two loops will get the job done.

This content is a combination of commonly known programming style guidelines, ideas that have been discussed here in our department, and Google Java style guide.