To this end, companies that employ programmers normally have a set of "Programming Standards" that all programmers must adhere to when they write code. There are similar standards for how you write code for CS-101, but instead of calling them "standards," I prefer to call them "guidelines" because I am willing to let you modify them in case you have another style that accomplishes the same goals as the rules given here.
I have an ulterior motive here, by the way. If you write your code following these guidelines, I will have a lot easier time grading your programs! I will be able to locate the code for your classes and methods quickly, I'll be able to understand the design of your methods easily, and I'll be able to locate and evaluate errors most readily. So, although we are working in an academic environment, there is a good parallel between your writing clear code for me to grade and your writing clear code for other programmers to maintain in the real world.
The number of spaces you indent for each lexical level is your choice, but I strongly recommend that you use a value of either two or four spaces. (I use two). The reason is that a larger number of spaces leads to very wide lines of code, which often end up wrapping around either as you enter them or when they are viewed later (by me). An indent of just one space is hard to read.
Exception: If there are no statements, or just one statement between a pair of braces, you may put the opening and closing brace on the same line.
It is a firm rule for this course that no lines in your code, whether Java statements or comments, are to extend beyond column 72.
<tab>characters in your code.
The advantage of
<tab> characters is that a
single character code in your program will automatically line
things up. The problem is that the "automatic" lining up has to be
done by software, either by your editor, by the software that
prints your code, or perhaps by a different editor that someone
else uses to view your code later on. But there is no universal
interpretation for these
<tab> codes, so your
editor might have tab stops set at every eight columns, the printer
might have them set at every five columns, and my editor might have
them set at every two columns. What a mess. Fortunately all
program editors provide an option to substitute the correct number
of spaces to give the effect as a
when you press the
Tab key on the keyboard, but by
putting in the correct number of space characters, the code always
looks the same whether it's in your editor, going to a printer, or
in my editor.
You must not press the
Tab key when editing a program
file using Notepad (Windows) or Pico (UNIX). These are primitive
text editors that cannot be set to substitute spaces for tabs; you
can't even set the tab spacing using these editors. Either type
the spaces to indent your code manually, or get a good programmer's
editor, such as the free Programmer's File Editor (PFE) described
on the [ Development
Tools ] web page.
A useful feature of PFE (and similar editors) is that you can
indent or unindent a block of statements by selecting them and
This feature is very useful when you change the lexical structure
of your code, such as by removing an
if statement, and
need to fix up the indentation.
//These comments have no //margin and are very //difficult to read. // These comments have two // spaces after the comment // leader (the //) and are // easier to read.
.javafile, even if the class is not public. This modular design will make it easier to maintain your code, because there is less code to deal with at a time.
The exceptions to this rule are anonymous and other inner classes. Since they are defined inside another class, they pretty obviously can't be defined in separate files.
Put a block of comments just before each class, interface, or method in each source file. These comments should start with a line that tells what is being defined, such as:
// Class Xyx or // Interface Abc or // Method abc()Then put a comment line with a row of dashes, or equal signs, or asterisks, or whatever you like to make the comment block easy to find when scrolling through the file. Don't use this type of comment line elsewhere; the idea is to show where a class, interface, or method begins, and nothing else.
Next put a "javadoc" comment block. (see [ below ] for information on running
javadoc.) A javadoc comment block starts with
(note there must be at least two asterisks) and ends with
*/. Asterisks at the beginning of lines inside a javadoc
comment block are ignored, but everything else will be used by javadoc
to generate HTML documentation for your code.
The first thing inside a javadoc block has to be a sentence (capitalize the first word and end with a period) that tells what the class, interface, or method does. The style for this sentence is to start with a present-tense verb with the name of the class, interface, or method as the implicit subject. For example, instead of saying "Interface Abc defines the methods that must ...", say "Defines the methods that must ...". There can be more than one sentence in the description, but early versions of javadoc limited the description to just one, and it's better to make your description brief rather than wordy.
After the description, use javadoc "tags" to tell about specific
features of the class, interface, or method. A javadoc tag starts with
@ character followed immediately by the name of the
tag. We will use just three of these javadoc tags for this course:
@authorThis tag goes in the javadoc comment block that goes before a class or interface. You may have more than one
@authortag in a file (for example when you use some code that I provided and added your own code to it), but the first
@authortag in every source file you submit must have your name and nothing else after your name on the line with the
@authortag. For example,
// @author J. Jones // @author C. Vickerywould be okay. But,
// @author J. Jones ID 123-45-6789would not be okay. The reason for this is not due to anything about javadoc. Rather, it's because I use programs to help me grade your programs, and my grading programs impose this requirement.
Note that "author" must be lower case and spelled correctly, and
that there must be no spaces between the
@ and the word
@paramThis tag goes in the comment block that goes at the beginning of a method. Use one
@paramtag for each parameter passed to the method, even if the method does not actually use the parameter (such as the command line arguments passed to main()). After the tag, put one or more spaces, the name of the parameter, one or more additional spaces, and a sentence describing the purpose of the parameter. The sentence may be continued onto the following line if necessary, but should be kept brief.
@return. This tag also goes in the comment block that goes at the beginning of a method. There should be just one
@returntag for each method. After the tag, put a sentence that describes the value returned by the method.
@throws. Use one of these tags for each exception type listed in the throws clause of a method, if there is one. After the tag, put the name of the type of exception that might be thrown, followed by a sentence that tells what situation would cause the method to throw the exception.
To run javadoc, first create a directory under your project
directory to hold the HTML files produced by javadoc. If you
named this directory
docs, the command to generate the
documentation for all the .java files in your project directory would be
javadoc -author -d docs *.javaYou need the
-authorswitch to get javadoc to process your
@authortags. They are ignored by default. The
-dswitch is immediately followed by the name of the directory where you want to save the HTML (and other) files generated by running the javadoc command. Finally,
*.javauses the asterisk wildcard to generate a list of all files that have names ending with .java.
You can view the files generated by javadoc by using a web browser,
even though you are not connected to the Internet. Use the browser's
File menu, select open, select the directory where you saved the HTML
output, and select the file named
index.html to start
browsing your documentation!
You can click on the following link now to look at the web pages generated by the Java 2 version of javadoc for the sample code given above: