CSC 210 Spring 2006 Coding Guidelines

Our guidelines are a derivative of those presented in the 160/161 textbook, L&L, Appendix F.

Why Bother?

A. Consistency is half the battle

  • Easier to share your code with others
  • Understanding your own "old" code
  • Easier to communicate when working in a group

B. Guidelines are not rules set in stone... not onerous

Design

A. Preparation... think, then code

B. Structured Programming

  • Do not use the continue statement
  • Only use the break statement to terminate cases in a switch statement
  • Only one return statement in a method, the last line, unless it makes things more complicated

C. Classes and Packages

  • If only one class is used from an imported package, then import that class by name. If two or more are imported, then use the * symbol

D. Modifiers

  • Do not declare variables with public visibility
  • If a variable is a constant, explicitly declare it with the final modifier
  • Use constants instead of literals in most situations

E. Exceptions

  • Use exception handling only for truly exceptional conditions, such as terminating errors, or for significantly unusual or important situations

F. Miscellaneous

  • Design methdos so that they perform one logical functions. Methods tend to be no longer than 50 lines, and are usually much shorter
  • Keep physical lines of source code less than 80 characters long, for nice printing

Style

A. Identifier names

  • Give identifiers a semantic meaning
  • Use "camel notation" for variables... start with lower case, begin new words with a capital letter, for example, professorPayRaise
  • Use UPPER CASE for constants and separate words with an underscore, like MAX_HEAD_ROOM
  • Capitalize class, package and interface names, like Tractor

B. Indentation

  • Use a consistent style of curly braces with methods, classes, if/then, switch, etc.
  • Almost always use curly braces with if/then statements

C. Spacing

  • Use white space to draw attention to important or complex part of your program
  • These are very optional:
    • Put one space after each comma in parameter list
    • Put one space on either side of a binary operator
    • Do not put spaces before a semicolon

D. Message and Prompts

  • Be informative, but succinct
  • Present information in a consistent manner

Documentation

A. The Reader

  • When commenting, assume that your reader is computer literate and knows Java
  • Use Javadoc for classes, methods and data fields, including tages: @author for classes, @param and @return for methods

B. In-line Comments

  • Use in-line comment to describe interesting or difficult code sections
  • Put a one-line comment above the line of code to which it refers