Achieving Readability in Java
Achieving Readability in Java
I pieced together these set of notes from similar notes written
by Nick Parlante of Stanford. I originally intended to make them
available for CPS606, Spring 1998. I beleive they can also be of
some use to CPS616 students. Feel free to let me know if you have
any suggestions to add to the contents, etc.
A program is undoubtedly read many more times than it is written. A
program must strive to be readable, not just to the programmer who
wrote it. Any program expresses an algorithm to the computer. A
program is considered clear or "readable" if it also does a good job
of communicating that algorithm to a human.
Readability is vital for projects involving more than one person. It's
also important when the program is of sufficient size that you come
across pieces of code you wrote, but which you don't remember. Beleive
me, it's a traumatic experience the first time it happens. A bug is
essentially a piece of code which does not say what the programmer
intended. So readable code is easier to debug since the discrepancy
between the intention and the code is easier to spot.
Documentation
Given that most programming languages are a rather cryptic means of
communication, an English description is often needed to understand
what a program is trying to accomplish or how it was
designed. Comments can provide information which is difficult or
impossible to get from reading the code. Some examples of information
worth documenting:
- General overview. What are the goals and requirements of this
program? this method?
- Data structures. How data is stored? How is it ordered, searched,
accessed?
- Design decisions. Why was a particular class design or algorithm
chosen? Were other strategies were tried and rejected?
- Error handling. How are error conditions handled? What assumptions
are made? What happens if those assumptions are violated?
- Nitty-gritty code details. Comments are invaluable for explaining
the inner workings of particularly complicated (often labeled
"clever") paths of the code.
- Planning for the future. How might one make modifications
or extension later?
- And much more ... (This list is by no means exhaustive)
Program Overview Comments
Everey program (or main class in a Java program) should begin with an
overview comment. The overview can be the single most important
comment in a program since it's the first thing that anyone reading
your code will read. The overview comment explains, in general terms,
what strategy the program uses to do its work. The overall program
overview should lay out a roadmap of how the algorithm is designed --
pointing out the important classes and discussing the data
behaviors. The program should mention the role of any other classes
which the program depends on. Essentially, the overview contains all
the information which is not specific or low-level enough to be in a
class or method comment, but which is helpful for understanding the
program as a whole.
In the latter paragraphs of the overview, you might include the
engineering rational for the classes constructed or the algorithm
chosen and discuss alternate approaches. The overview can also
introduce the programmer's opinions or suggestions. It's often
interesting to see the programmer's feelings on which parts of the
program were the hardest or most interesting, or which parts most need
to be improved.
For coursework, the overview should also include uninteresting but
vital information like: your name, what class the program is for, and
when the program is being handed in.
Class Comments
Saleh Elmohamed, saleh@npac.syr.edu