Coding Conventions

Below are coding conventions we will use in our Java programming. This is a living document which you are expected to provide feedback on if you would like a convention added or altered. (These are your coding conventions to own and determine. This page is just where it’s hosted.)

In later assignments, there will be points allocated in the grading for adhering to correct coding style conventions.

Is this just to make the teacher’s life easier??

It most certainly makes me happy! But agreeing to and following coding conventions is an industry practice. (For example, see Sun’s recommended conventions for Java.)

Sun states that 80% of the lifetime cost of a piece of software goes to code maintenance. Very little code is maintained for its whole life by the original author. (Think about it. Windows XP was released on August 24, 2001. Those developers have long since been promoted and have left for Facebook.)

Okay, okay. I jest. In all seriousness, software engineers frequently move to new teams and projects, meaning the authors often leave and new developers often face old code. Code conventions improve the readability of software. This enables engineers, developers, and programmers to understand code that is new to them faster and more thoroughly.

Roosevelt CS Coding Conventions

 

(updated December 2, 2014)

NAMING

Names must clearly describe the element they represent. “Beautiful, Readable Code!”

  • Classes: nouns in mixed case with first letter of internal words capitalized (e.g., CorrectClassCapitalization)
  • Methods: verbs in mixed case with first letter lowercase and first letter of internal words capitalized (e.g., correctMethodName)
  • Variables: mixed case with first letter lowercase and first letter of internal words capitalized (e.g., correctVariableName)

INDENTATION

Consistent and clear indentation is essential.

  • Increase level of indentation after all opening curly braces
  • Stay at a single level of indentation for an entire block
  • Close curly braces at the same level as the corresponding opening curly brace

Class Comments

Each class must have a comment in this format.

/**
 * ClassName.java
 * Assignment: Name of Assignment
 * Purpose: What concepts does this assignment have  
 *   you practice? This answer should be the
 *   same for all classes.
 *
 * @version mm/dd/yy
 */

Comments

  • Method comments: Single line comment provided for every method (comment on main not required, if code is readable and class comment adequately explains). For examples of what is appropriate single line comments for methods, see Java documentation (javadoc) for classes such as World (from the 2008-2014 AP CS A Case Study), String, and Math.
  • Complex code comments: Single line comments as necessary for complex portions of code (where it’d be easier to understand by reading a short comment than reading even the best “Beautiful, Readable Code” you can write).

Other Formatting

  • New lines: Start a new line after every “;” or “}”
  • Space between methods: Skip exactly one line between methods
  • Main placement: Main must be at the top
  • Line length: Limit lines to 100 characters or less