Using a good coding style is important, for many reasons.
Professional programmers need not only to be able to read and
understand their own code, months or even years after originally
writing it, but also to be able to read and understand code written by
others, oftentimes in the absence of the original programmer.
Programmers who write code in a clear style with adequate documentation
benefit not only themselves, but all other member of their team, as
well as future members of the team. There is nothing more frustrating
as a programmer than inheriting responsibility for someone else's code,
only to find that the code is designed poorly, written cryptically, and
documented shabbily (or not at all!). Yet much of the code that I've
inherited during my career has exhibited one or more of these
shortcomings!
The Java code that you write for this course should follow the style and documentation conventions described in the list below.
- Matching opening and closing curly braces should be aligned
in the same column. This means that the opening curly brace which
follows an if statement should appear directly below the letter i in if, and not on the same line as the conditional expression.
- All
statements within curly braces should be indented four spaces (or one
TAB character) relative to the brace. A statement should not appear on
the same line as the opening curly brace.
- The names that you use for variables, parameters, methods, and classes should be meaningful. Exception: Counters or other loop control variables may have simple names such as i or p.
- All
constants in your program should be defined and named meaningfully. For
example, if you were writing an array implementation of a stack with a
hard-coded maximum size of 256 elements, define a static final field
such as MAXIMUM_ELEMENTS, and use that field in your code, rather than
the literal integer 256.
- Naming conventions for classes, members, and constants:
- Class
names should be capitalized. Class names with multiple words should
have each subsequent word capitalized, with no underscore separating
the words. (e.g. Song, ReggaeSong)
- Names of class
members (methods and fields) should begin with a lowercase letter.
Subsequent words should be capitalized, with no underscore separating
the words. (e.g. playSong(), songTitle)
- Named constants
should be named using all capital letters, with underscores separating
the words. (e.g. EULER, MAXIMUM_ELEMENTS)
- Every member should be declared using an access-control modifier (e.g. public, private, or protected).
- Whitespace should appear between each method argument and around each binary operator. For example, createFile("alex.out", WRITE) instead of createFile("alex.out",WRITE), or a + b instead of a+b.
- One
single line of code should not be inordinately long. What constitutes
"inordinately long" is largely a matter of taste, but a good rule of
thumb is not to write lines of code that are longer than 80 characters.
Don't be afraid to break up long lines into multiple lines. For
example, if you have a method call with fifteen parameters, put some on
one line, some on the next, etc., such that each line is no longer than
80 characters.
- Every class, method, and field should have a
comment which briefly explains its purpose. In the case of methods,
some explanation of the meaning of the method's parameters is expected.
- Within the body of your methods, code whose purpose is not readily obvious should be commented. It is not
necessary to include a comment on every line. It is appropriate,
instead, to have one comment which explains the purpose of a chunk of
several lines of code.
A good example of many of these coding practices can be found by
looking
at the various starting points provided for each project. Some of these
files do not follow all of the rules above, particularly the rule
regarding a comment on every method (since we expect you to write these
comments yourself, in most cases), but they are still a useful way to
see these rules in action.