You only write code once, but read it many times. Having clean, organized, legible, intuitive, and understandable code is important for those who read it: whether it be for debugging purposes (yourself, a peer, or a TA), for style grades (a TA), or even for judging your coding abilities and organization (a potential employer/co-worker). Yes, your code may run and solve a given problem whether it is organized or not. But, writing your code in a clean and organized way from the start will benefit you in the long run.
Any code you submit must compile. If it does not compile, we won’t grade the assignment and you will lose all the points for the assignment.
If you find yourself writing the same or similar code two or more times, consider whether it could be put in a separate method.
No line of code should have more than 100 columns. Using more than 100 columns
causes your code to wrap around to the next line, which adversely impacts
readability. You can set a visible margin in Eclipse by going to
"Editors" > "Text Editors" > "Show print margin".
Do not use tab characters for indentation. Make sure indentation lines up correctly. Please use 4 spaces for a tab.
Although curly braces aren’t required for one statement, it’s good style to always include them. Doing so can help you avoid easily prevented bugs.
Fortunately, Eclipse has a code formatter that will automatically fix these
above three points for you! Simply press
Cmd-Shift-F for Macs)
to automagically format your code. Set up the formatter by going to
"Preferences" > "Java" > "Code Style" > "Formatter".
Consider the following:
// BAD: double magnitude = Math.pow(x, 2) * Math.pow(y, 2); // Computes the magnitude of a vector // GOOD: // Computes the magnitude of a vector double magnitude = Math.pow(x, 2) * Math.pow(y, 2);
The latter is the better style.
Your code should be readable in many cases without comments. This is called self-documenting code. Comments that merely repeat the code they reference or that state the obvious are a travesty to programmers. Comments should state the invariants, the non-obvious, or any references that have more information about the code.
Incredibly long comments are not very useful. Long comments should only appear at the top of a file—here you should explain the overall design of the code and reference any sources that have more information about the algorithms or data structures. Rarely should you need to comment within a function—variable naming should be enough.
When comments are printed on paper, the reader lacks the advantage of color
highlighting performed by an editor such as Emacs. This makes it important for
you to distinguish comments from code. When a comment extends beyond one line,
it should be preceded with a
* similar to the following:
/* * This is one of those rare but long comments that need * to span multiple lines because the code is unusually * complex and requires extra explanation. */
Ever wonder how the thousands of Java API web pages are generated? Using Javadoc, an Oracle tool that generates API documentation in HTML format! Refer to Oracle’s how-to for Javadoc for further details.
Variable names should describe what they are for. Distinguishing what a variable references is best done by following a particular naming convention (see Item 10). Variable names should be words or combinations of words.
By convention, Java uses camelCase.
Variables and functions are usually verbs, and are written in
camelCase. The first letter is lowercase.
Getter and setter methods should begin with the verbs
Methods that return a
boolean generally begin with the verbs
Classes names are usually nouns, and are given in
camelCase rule as above, and capitalize the first letter. Examples:
Constants (variables marked
static final) and enumeration members
are usually written in
ANGRY_CASE. Capitalize all letters, with
underscores between multiple words. Examples:
In Clean Code, Bob Martin asserts that methods should hardly ever be more than 20 lines long. While this guideline may be hard to always adhere to, if your method starts to look bloated, consider breaking it into smaller, logically-separated helper methods.
The Java standard libraries provide implementations of a great number of methods and data structures—use them! The java.util package will prove especially useful in this course.
Follow test-driven development! Set up test cases before you write your code. Doing so will help you better understand the behavior of the algorithm or solution you are implementing.
Use getters and setters instead. If a class
Point has an instance variable
and you are working with a
Point point, you should not find yourself writing
point.x. Instead, declare
x as a (package-)private variable, and write a
point.getX(). One exception in which this rule may be waived is
if the variable
x is marked as final, and only if
x is immutable.