CS120 Style Conventions (Fall 2017)

This page sets forth a few simple style guidelines for CS120 in Fall 2017.

This document is brief — we impose few style rules centrally. However, you are expected to be consistent in your coding style across an assignment. If you choose, for example, to indent by three spaces in one method of an assignment, then indent by three spaces throughout that assignment.

  • Every Java file of your assignment should start with the following header:

    /* FILE.java
     *
     * SHORT (ONE-LINE) DESCRIPTION OF THE FILE.
     *
     * Author: NAME
     * Derived from: SOURCES (omit this line if the code is all original)
     *  - (If multiple sources, give each its own line)
     *
     * LONGER (A PARAGRAPH OR TWO) DESCRIPTION OF THE FILE CONTENTS
     *
     */
    

    where you replace NAME with your name, and so forth.

  • Do not use tabs; use spaces instead. You should be able to configure your editor to insert an appropriate number of spaces when you press the tab key.
  • Use 2-4 spaces per level of indentation. Again, pick a number and stick with it, at least within each assignment. “2-4 spaces” does not mean 2 spaces for one block, 4 for the next!
  • Code lines should not be excessively wide. With rare exception, lines of code should not exceed 100 characters.
  • Once we discuss methods and Javadoc, use Javadoc comments for all classes, method, variable, constant and other declarations.
  • Once we discuss the final keyword, use it wherever possible.
  • Use //-style comments to explain your algorithm. Intermix these comments with the various statements (or groups of statements), if and switch blocks, case clauses, and loops as appropriate.
    • Please these comments right above the relevant statements, indented the same distance as the first line of the block they are describing.
    • Use standard, clear, simple grammatical English writing in comments, with mostly complete sentences.
    • Use mixed-case text, except possibly to highlight the beginning of a section: all-capitals looks like shouting and is hard to read in bulk; all-lower case tends to blur sentences and thoughts together.
    • Make sure there is a single space after the /, and that the /‘s from different lines of one comment are vertically aligned.
    • Since they are English-language text intended for the human reader, lines of comments should not exceed 80 characters. Multiple lines of text are much easier for the human mind to read than excessively wide lines.

Other style resources