Program Commenting Guides
Good commenting is concise, meaningful, and compatible with automatic
documentation generation engines, such as Doxygen or Javadoc. Good
commenting makes code more reusable and sustainable by making the code
easier to read for developres who maintain and extend it over time.
Good commenting involves documenting the head of every method, in-line
comments beside single statements whose purpose may be non-obvious, a
block of comments before a loop whose operation may be non-obvious or
obscure, etc. In short, good commenting--combined with good
programming style--makes software easier to read and understand.
The following are some guidelines for commenting Java programs:
- Commenting classes and interfaces in your *.java files.
This is absolutely critical. Don't leave even a single class,
interface, method, or field uncommented. If other people ever use
your code in a project of theirs, the *.java files (or auto-generated
documentation) will often be where they go to learn how your code
works. Uncommented methods and instance variables are the kiss of
death.
- Comments at the head of methods. Good comments at the head
of a method will have the method name; its purpose; and its
parameters, return values, and types, along with a description of what
each of these parameters and return values represent. A minimal
comment at the head of a method will have a description of the
method's purpose.
- In-line comments. If you write a ridiculously-complicated
one-liner, it should be commented. If you make a check whose purpose
is not immediately obvious, it should be commented. It's fine if you
address all these points in a single block comment before a loop or an
implementation of an algorithm, as long as they're noted
somewhere.
- Java Streams Each and every aggregate operation (i.e.,
intermediate operation and/or terminal operation) should have a
comment. When in doubt, look at the example code we walk through in
class from my GitHub
repo.
In my experience, there is a strong correlation between efficient,
elegant code and well-commented, well-structured, and maintainable
code. Writing readable code with effective comments is therefore
vitally important. Therefore, code that's not documented will not be
reviewed.
Back to Douglas C. Schmidt's
home page.