What goes in a Java file

1

• What goes in a Java file
• One class per file, one idea per class
• don't mix applications with support classes
• Comment at the beginning has bookkeeping
  information (author, date, version) and explains
  what the class does

2
Page Format

• Reader should be able to see the idea all at once
• Assume that a page is 24 lines by 80 columns
• Method definitions should not exceed one page
• Split lines at logical places before they
  over-run

veryLongVariableName (evenLongerVariableName
anotherLongOne)
longestEverVariableName veryLongVariableName
anotherBigOne.longMethodName(argumentOne,

argumentTwo) veryLongVariableName
anotherBigOne.longMethodName(
aLongerArgumentOne,

aLongerArgumentTwo
)
3
Code Order

• Variable declarations precede methods in a class
• Variable declarations precede executable code in
  a method
• (There is an alternative view that variables
  should be declared just immediately before they
  are first used.)

public class Example private int
exceptionCount private int headline
public String toString() private
String tempHeadline ..

4
Variable Names

• Variable names are descriptive
• variable names describe meaning, not data type
• (this is contrary to the C convention)
• descriptive generally means long
• but not too long
• book says avoid abbreviations like cnt for
  current
• I'm not so sure, because the variable names can
  get extremely long
• capitalization
• class names are always capitalized
• method and variable names always begin with lower
  case, with no punctuation, and words capitalized
• constants are in all capitals, with underscores
  separating words (MAX_LINE_LENGTH)

double highestSalary String bestCandidateName in
t maximumTaxRate double currentCandidateForHighes
tSalaryInList // XX avoid the prepositions!
5
Vertical Spacing

• Using blank lines
• blank lines communicate breaks in parts of the
  program structure, and also different parts of
  the program logic

public class PlayingCard private int
rank private String suit public
PlayingCard (int r, String s) int
tempRank // initialize variables and
other state ..
// computation phase ..
// clean up and return
..
6
Horizontal Spacing -- Indentation

• When a single code statement is broken across
  lines, indent to communicate the logical
  structure of the statement
• multiple arguments to a method at same indent
  level
• arguments to an operator at the same indent level
  (?)
• sub-expression indented past the main expression
• When introducing a new code block ( ) indent
  the code in the block either with one tab or
  three spaces

public static void main(String args) //
all lines start here or to the right
public static void main(String args) //
all lines start here or to the right
7
White Space in the Line

• Put one space after each comma in a parameter
  list
• Put one space on either side of a binary operator
• Do not put spaces immediately after a left
  parenthesis or before a right parenthesis
• Do not put spaces before a semicolon
• Put one space before a left parenthesis, except
  before an empty parameter list (??!?)
  "hello".concat ("world") "hello".length()
• Put a single space between empty parentheses or
  brackets ( )
• Put a single space after each comma in an
  argument list"hello".substring(2, 4)

8
Comments

• How to insert them, where to insert them, and
  what they should say

/ This is a block comment, and it is also a
Javadoc comment. I can put HTML
in the comment, and also special tags like
this _at_author Steve Hanks which will be
used by the Javadoc program to produce API
web pages automatically. /
// For one or two lines of comments, // use
this format int i, j String name
// Short explanations of a single code line go
here CardDeck.shuffle( )
/ This is a block comment, but it is not a
Javadoc comment. Block comment just means is
spans multiple lines /
// Very rarely, a comment can go on the end of a
line Payroll.fire(anEmployee) // OK if
employee is already gone
(Insert a blank line between a block comment and
code no blank line between a single-line
comment and code.)
//
// This is a different format
for multi-line comments. // The important thing
is the header line, which separates // comments
from code //

9
Required Comments

• At the beginning of every source file (class
  declaration), you must have a block comment first
  with bookkeeping information, then describing
  what the class does
• At the beginning of ever method definition, a
  (possibly short) block comment describing what
  the method does
• do not repeat the method signature your reader
  can see that
• The rest is more subjective. Places one commonly
  puts comments
• single-line comment before a variable, explaining
  what the variable does (if necessary)
• single-line comment before a line or block of
  code, explaining what the code does (if
  necessary)
• but do not insult your reader's intelligence by
  stating the obvious!!!!

int maxPossibleSalary // maximum possible
salary int y y maxPossibleSalary 5 // add
5 to max salary assign result to y
10
Summary on Code Formatting Standards

• There is only one real point readability
• The main way you get readability is through
  consistency
• internally
• across an organization
• For this class, you should adhere to these
  standards. (Mainly because it's good practice to
  get used to understanding and adhering to
  standards you will have to at some point in the
  future.)
• You should make sure that even when the standards
  give you some leeway, be internally consistent.
• Most of all, be sensitive to your reader a
  fellow Java programmer who is trying to
  understand what you are doing
• explain your task (at the beginning of the file /
  class)
• explain your strategy (at the beginning of each
  method)
• explain things that might be obscure to the
  first-time reader
• but don't over-explain