The fundamental purpose of documentation is to enhance the readability of your code—that is, to make it easier for future readers of your code (very much including you-a-week-from-now) to understanding what your code is supposed to do. On this page, I describe my expectations for the readability of the code you submit to me.
Style refers primarily to the way your code appears on the screen/page. It also encompasses some ideas about the design of your code—mostly, techniques you should avoid because they are likely to break in the future. The Internet has many examples of excellent Java style guides; I recommend the GitHub Java Style Guide. As you read through it, you will probably see many unfamiliar terms and concepts. Don't worry. Look for what the guide says about familiar elements of coding practice; when you come back to the guide later in the semester, you'll understand more—and if you return to it in a year, you'll understand even more.
Documentation refers to the non-executable text that describes the design and intended behavior of the executable part of your code. Style guides sometimes provide guidance about how to write and structure your documentation. Below, I describe what kinds of documentation you need to provide for projects in this class.
Project documentation comes in three flavors:
While good style dictates that your code be as "self-documenting" as possible, through the use of descriptive-but-brief variable names, it also dictates that you comment on anything that's not "obvious."
This is where most of your documentation effort should go.
In the project skeletons I provide you, you will see some
simple HTML documentation. This was produced
from my comments using Javadoc—note that class and method
comments all begin with two stars and occasionally use
javadoc notation like
@see
and
@param
. You should revise and augment this documentation as
needed. See this explanation of how doccomments are best written.
When you want to see what your documentation looks like, in
Eclipse look under the Project menu for "Generate
JavaDoc..."—you shouldn't need to alter any of the
default settings. Note that Git/GitHub will commit your
documentation (in the
doc
folder) along with the rest of your project, though you
may have to make sure the folder is included in your
repository.
README.md
file. It should be clear how to get started on writing this
file, but for more information on how it can be formatted (using
"Github-Flavored Markdown"), read this
about markdown basics.