The way you present your program is just as important as having a
correct program. While having good comments or good variable names
will not affect the correctness of your program, it will make it
easier to read your program. It is important that others be able to
understand your code so that they can modify your code if they have
to. A significant component of your lab grade will be determined by your programming
style.
This is a guide to help you better understand what we are looking for
when we look at your labs. As the semester progresses there will be
steeper penalties for styling mistakes. So, get into the habit of
writing good labs from the beginning. After writing your lab be sure
to look over your code and your style.
Comments are extremely important. Take some care to write accurate
yet concise comments.
- Be specific with your comments. What happens when the button
is pressed? What is the JTextField used for? Your
comments should describe the intent of the code. What are you
trying to accomplish with this piece of code?
- Do not make your comments (or code) too wide. Any line of comment or
code that is over 80 characters should be split up over several lines.
If many lines in
your program do not print nicely, the TA will find it difficult to read.
- Do not overcomment! Overcommenting can make the program
hard to read just as much as under-commenting. Do not comment
every line. If your instructions are simple and clear, most people will
understand them without your comments. If you think you need
commenting, try commenting chunks of code under the same comment.
- Delete any extraneous code. You would not
hand in an English paper with crossed out lines. Similarly, you
should not hand in a lab with commented out code. Remove all code
that your program no longer uses.
You should write comments for:
- Class (Program): At the top of each class, you should write
your name and a brief description of what the
class is for. If you decide to do more than the assignment
requested, you should describe these "extra" features in the
program under the class description. Sometimes it's hard to tell
a bug from a feature.
- Methods: Above each method heading there
should be a brief description of what the method does. You should
also describe what each parameter means and what the return result
means. If the method code is simple you do not need to comment in
the method body. If the method body is complicated, you might
want to add some comments to certain areas that you deem to be
complicated. Be careful not to overcomment!
- Variables and constants: In general, variables and constants
should all have comments as to what the variable is used for. For
example a good comment for your the variable JTextField messageNum
might be: // The number of the email message to retreive
(rather than, say, // message number).
Frequently, several closely related variables or
constants can be grouped together under the same comment.
Blank lines are used to delineate different areas of the code. The
instance variable declarations at the top of your program should be
separated from the header of the class and the header of the first
method. There should always be a blank line between methods. It is
advisable to break up long method bodies and long declarations into
logical pieces. Always start a new line after a semicolon.
You should always choose names that suggest the meanings of the things
being named. If the purpose of a method is to remove all the blanks
from a string, then a good name for that method is
removeBlanks.
If there is a variable of type
int that is used to refer to the total
number of message that have been sent,
then a good name would be
messagesSent or
messageCount.
- Names that have nothing to do with the program are very bad
names! Ex. NetConnection harry
- Names that are not specific or descriptive enough are
generally bad names. Ex. String string or String p
are not as good as String password if the variable will
refer to someone's password.
- Try not to name objects sequentially. You should only do
this when the objects are related in some way that is not
otherwise expressible. Ex.,
JTextField field1, JTextField field2,
JTextField field2 are not as good as serverName,
port, and messageNum if the text fields
are used to input a server name, a port number, and a message number.
By convention, constants (indicated by "
final" in
Java) are all capital letters, classes begin with uppercase, variable
and method names begin with lowercase, while uppercase is used to start
new words in multi-word names.
Instance variables should always be declared to be private. Whenever
possible, names should be declared as local variables rather than
instance variables. Instance
variables should only be used when a value must be saved for use
after the execution of a method or constructor is completed.
Your program should be formatted as neatly as possible.
The statements and declarations placed in a method's body should
be indented about 4 spaces more than the method's header. Similarly, the bodies
of while loops, and if statements should be indented slightly compared to the
headers of these constructs. Sequences of
statements that do not contain if statements, while loops or other control
constructs should all be indented by the same amount.
