CS18 Java Style Guide Spring 2020
Every time a case in a
switch
statement falls through (i.e., doesn’t include a
break
), add a comment
where the
break
statement would normally be that says something like
/
*
falls through
*
/
.
This way the reader of the code need not question whether the missing break was deliberate.
Every
switch
statement must include a
default
case. The
break
in the default case is redundant,
but it can prevent a fall-through error if another case is inserted later.
5.10 try-catch Statements
A try-catch statement should have the following form:
try {
statements;
} catch (ExceptionClass e) {
statements;
}
Likewise, a try-catch-finally statement should have the following form:
try {
statements;
} catch (ExceptionClass e) {
statements;
} finally {
statements;
}
6 Comments
Java programs can have two kinds of comments: implementation comments and documentation
comments. Implementation comments are those originally used in C, which are delimited by
/
*
...
*
/
, and
//
. Documentation comments (a.k.a “doc comments”) are Java-only, and are delimited by
/
**
...
*
/. Doc comments can be exported to HTML files using the javadoc tool.
Implementation comments are meant for comments about the particular implementation. Doc com-
ments are meant to describe the specification of the code, from an implementation-free perspective,
to be read by developers (or TAs) who might not necessarily have the source code at hand.
Comments should be used to give an overview of code, and to provide additional information that is
not readily available in the code itself. Discussion of non-trivial or non-obvious design decisions is
appropriate, but avoid duplicating information that is present in (and clear from) the code.
Excessive commenting can be indicative of poor code quality. When you feel compelled to add a
comment, consider rewriting the code to make it clearer.
Comments should contain only information that is relevant to reading and understanding the
program. Information about how the corresponding package is built or in what directory it resides
should not be included as a comment.
Comments should not be enclosed in large boxes drawn with asterisks around them, or any other
characters. And they should never include any special characters, like back space or line break.
10