Naming
Classes, Interfaces, Enums
It is difficult to explain exactly what makes a good name, but
there are plenty of bad ways to name your classes. You want every file
that you create to have a concise name that reflects what it does. A
class that is named Word
should not be running a
simulation of a galaxy.
You should avoid names that don't convery much information,
like Data
, Info
, or Engine
.
You should also avoid tacking these unhelpful words onto
otherwise good names. If you have a class that represents a star,
call it Star
, not StarData
.
A good way to name interfaces is to name it according to what can
be done with classes that implement that interface. For example, an
interface that represents something that has spatial coordinates can
be named SpatiallyLocatable
. This makes it easier to
recognize an interface compared to a class.
Methods
Method should also have informative names. do()
is not
a good name for a method.
With regards to accessors and mutators, there are two commonly used formats:
value()
andvalue(newvalue)
- JavaBeans style -
getValue()
andsetValue(newvalue)
We prefer JavaBeans style because many tools in the Java "ecosystem" assume you will use that style.
Fields
We do not visually distinguish instance fields from local variables. Some style guides encourage a style that starts or ends fields with an underscore. We do not. Instead, we ask you to keep your classes and methods simple enough that confusion is unlikely.
Static field names should be all uppercase, for
example static int BEST_NUMBER = 1338
. Quite often
they'll be final
too. Static or not, you should mark a
field final
if it is not intended to be reassigned. We
love immutable classes.
Encapsulation and Package Structure
Make sure to employ proper information-hiding in your
classes. Fields in your classes should never be declared public in
order to ensure that outside forces can't modify your fields. You
should use accessors and mutators to allow outside access to your
instance variables (only if they need to be modified!), which allows
the programmer much more control. You can, for example,
prevent setAge(-3);
from working if that is
nonsensical. Be sure that your getters do not hand out references
to modifiable inner state of your class.
Java has four levels of visibility for fields, which are described
in
detail here. Most
of the time it is appropriate to use the private
keyword, and write accessors and/or mutators for the private
field. However, in some cases it is better to use no modifier,
making the field available to all classes in the same package. This
is useful when you are implementing a part of your program that
requires multiple classes working together. For example, if you are
implementing a Graph class, you will probably also need Node and
Edge classes, and the fields of Node and Edge might be
package-visible so Graph can easily manage them. A more
conservative strategy is to make fields private, and make the
getters and setters package private.
You should be using packages wisely. You might have one package
named after the project in question, and it might have
only Main
and a few very project specific classes. If
you build a data-structure, you might have a package for the that
type of structure. For example, List
is in
the collect
package with many other kinds of
collections. Resist the urge to have a util
package.
That's a sin of the same variety as naming your
class Data
Coding Style
Exceptions
Handle exceptions! We see code like this too often:
try {
something();
} catch (SomethingException e){
e.printStackTrace();
}
Don't do this . This defeats the purpose of having exceptions if you just ignore them and print an almost always useless (to the user) stack trace. A user should never be exposed to your program internals in this fashion, so printing stack traces will be treated like an uncaught exception.
Iterators
If you wish to use an iterator, please use a for-each loop rather than a for loop whenever possible. You intent is clearer, and the code is easier to digest (by humans).
Comments
Write useful comments. There are two types of comments we expect.
Method Comments — If the method is public, it should have
javadoc style comments. Javadocs are like regular multi-line
comments, except they are delimited by /**
and */
instead of the usual /*
and */
. You can generate documentation from your
javadoc using mvn site
as described in
the boggle project.
A concise guide is to Javadocs can be found here:
http://students.cs.byu.edu/~cs340ta/fall2018/help/javadoctutorial.php
A more complete guide can be found here:
http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html
Inline Comments — When writing a method you should always comment on what the method will be doing and what needs to be done. Inline comments will help you figure out what has been done and what needs to be done. Also it will help people look at your code and understand what it is actually doing.
README
There are a few things we require you to write in the README.
Errors/Bugs - Write about all the errors that your program has and how to reproduce them. If a TA finds an error and knows how to reproduce it, he/she will be able to correct it and grade it more accordingly. It won't help you to cover up your errors. The TA will probably end up finding it and assume you did not test your program properly.
Design Decisions - We expect you to write about the design decisions you have made for the project. If you don't think a regular person could come up with the algorithm you wrote, explain how it works. Don't be too specific, the lower level explanation should be in inline comments. Finally, also discuss why you chose to use certain data structure or why you created one, all high level explanations as well.
Tests - Talk about all the tests that have been written for the assignment. Explain how each test ensures that a part of the program works.