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.