Code style will be a portion of the grade on CS 2110 assignments. Please familiarize yourself with these guidelines, some of which are standard Java practice, while others are intended to develop good coding habits.
When in doubt, choose the alternative that makes the code most obviously correct: "There are two ways of constructing a software design. One way is to make it so simple that there are obviously no deficiencies. And the other way is to make it so complicated that there are no obvious deficiencies." - C.A.R. Hoare.
Remember that you're writing code for an audience. Other people are going to be reading it, trying to understand what you're doing, and you should make it as easy as possible for them to do this. This means: Leave good comments. Good comments explain the logic of what's going on. Don't make your audience strain just to figure out what your code is supposed to do. At the same time, though, it is possible to leave too many comments. Statements like "i++;" are self-explanatory. The comments should be at a higher level of abstraction than the code: Don't just translate Java into English. Summarize.
In CS 2110, we will adhere to Java's naming conventions. These may seem arbitrary and bizarre if you're not used to them. Nonetheless, conforming to aesthetic standards of coding is something you'll need to do in any just about any software development workplace*, so it's good practice.
Java class, field, method, and variable names are written in CamelCase. Words are smashed together, and the first letter of each word capitalized. There is no underscore or other word separator. Class and interface names begin with a capital letter:
Fields and methods begin with a lowercase letter:
Additionally, method names should be verbs describing what the methods do. Sun's JDK is sometimes inconsistent about this, though, so we'll be lenient.
There is one exception to CamelCase variable names: Constants. Here, we will stick to a convention borrowed from C. Constants are in all-caps with words separated by underscores. Constants should also have the keyword final, and are usually static:
Variable names should give the reader some hint about what the variable is used for. There are a few exceptions, like i and j as counter variables or e as the Throwable in a catch block, but speaking generally variable names should be descriptive.
If you find yourself wanting to name a variable something likevar, data, ortemp, stop and ask, "What does this variable really mean?" Using a meaningless name gives up a chance to further document your code.
It may feel like you're a cool hacker if every variable in your program has a short, unreadable name. However, this can become a nightmare for yourself or others to read:
You can use the default package names assigned by Eclipse unless the assignment explicitly asks you to do something else.
As a general rule of thumb, if a single method is getting beyond a few pages of code, you might want to consider lifting some of that method's functionality into other methods. Similarly, if you find yourself pasting the exact same chunk of code into multiple places, you might want to create a single method that does the job. The Refactor contextual menu in Eclipse can help with this.
However, it is possible to go overboard with this. Even if two blocks of code are structurally similar, don't merge them into the same method if they do different things. Each method should have only one purpose. Names like saveOrLoadAnimal() are a clue that you really need two methods:saveAnimal() and loadAnimal().
Be consistent with your code formatting, and indent code blocks. Don't write huge lines of code that wrap around the screen. Eclipse can help with this: Try the Format option under the Source menu (Shift+Ctrl F), and the Correct Indentation feature (Ctrl I).
Depending on where you learned Java, you may have picked up some out-dated habits. Habits that are going to raise eyebrows at a job interview. In CS 2110, our goal is to make you into the best programmers we can, and that means using certain new syntax and features added in Java 1.5, and avoiding patterns used in earlier versions of Java or carried over from other languages like C.
When using collections like those derived from List, Map, and Set, use appropriate type parameters:
We'll cover generics later in class, so if you don't know all the theory behind type parameters, that's okay for now. Just use them.
Eclipse will give warnings if these type parameters are ignored.
When you're writing a for loop that iterates over an array or an Iterable (such as ArrayList, etc), please use the new for-loop syntax when possible:
There are cases when you might want to explicitly create an iterator, such as if you want to remove elementsin situ. That's all right, but leave comments explaining why you've decided not to use Java 1.5's for-loop syntax.
Similarly, don't use an integer counter variable to index into an array or List if you really just want to iterate:
Of course, there are exceptions to this rule. Numerical algorithms, such as factoring a matrix, will certainly want to use integer indices for arrays.
Java defines four levels of access: Public, private, protected, and default (i.e., no modifier specified). Your methods and fields should be private unless there is a reason for them to be otherwise. However, when grading, we will not be pedantic about the nuances between public and protected. Please don't use default unless you leave a comment justifying it.
In most cases, client code doesn't care about the implementation of the list - it just wants to know what operations are supported. Specifying a linked list is needlessly providing a detail that makes future changes harder.
The following is just begging for a bug:
Can you spot the bug here?
Always use brackets:
(This applies to other structures as well, like else while, for, etc.)
It is also recommended to put a space between the keyword and the parenthesis, to differentiate control structures from method calls:
For group projects, be sure to credit co-authors in your README assignment write-up. For all assignments, please credit any classmates or friends that you talked with ("Talked with Ken, he showed me the right way to use a HashMap"). For non-group projects, other students should not help you with your assignments, but helping each other with general class material is acceptable. You don't need to credit TAs or consultants for their help.
In general, it is acceptable to copy short snippets of code from the internet, provided you credit their sources. Include a URL and the author's name (if known) in the comments.