Notes on Assignment 02

These are some of the general comments I had on your second assignment (and on a similar assignment I gave to 223). Most of you have the same or similar comments on your grade sheets, but I may have forgotten to include some of them when appropriate.

javadoc

• You don't need to restate the name of the class or method when writing javadoc documentation.
• You should separate the general commands from the "@tags" with a blank line (or one that just has a * on it).
• Your javadoc comments must come directly before each class or method. In particular, you can't have import statements in between the documentation and the class definition.

Coding Style

• You can help verify that your program works correctly by writing separate test programs for each of your classes.
• I'd recommend against using true/false values to represent which player is up (yes, I know we talked about it in class, but it's not the best design).

Methods and code length

• Many of you have incredibly repetitious code, differing only in a few variable names. You should turn such repetitious code into a single method, and call it with different parameters.
• I was once told that no method should take significantly more than one screen (24 or so lines). While this isn't quite true, you should generally break up your larger methods into calls to smaller methods.

Naming

• Try to use meaningful names instead of single letters. Using x for "probability of player one winning a serve" is unintuitive.
• Upon further consideration, I've decided that you should do your best to follow the naming standards set in the Java API.
  • Class names always begin with an uppercase letter.
  • Method names begin with a lowercase letter nad have mixed case.
  • Variables names are all lowercase.

Error Checking

• Many of you need to do better error checking of input from the command line (e.g., that the number of arguments is correct and that they are in the appropriate range).
• In the future, you should be using exceptions for these types of problems.

Constants

• Don't encode results in integers unless you've defined constants that correspond to those integers. Many of you return something like 3 to indicate "player 1 won by shutout". That's a pain to decode.
• Don't hard-code numbers like 1000 (the number of games). Use constants!
• You can declare constants with
  public static final type constant = value

Comments

• Any classes that define main() routines need to have instructions for calling the class in the comments (and not just in the code).
• I'd like to see more of you comment your right braces.
• It would be nice to see overall documentation for your program, describing the relationships between classes.
• I was serious when I said that every four or so lines of code should most likely have a high-level comment.
• I'd strongly recommend using the // style comments for your in-code comments. (This makes it easier to "comment out" a block of code.)
• From now on, you should be using pre- and post-conditions.

Readability Issues

• Include whitespace between separate methods.
• Don't be afraid to use some returns in your code, especially in long tests.
• In general, right braces should be on lines by themselves, and open braces should not be followed by anything.
• It's better if the differences in names come at the beginning, rather than the end, of the names. E.g., use a_player and b_player rather than player_a and player_b.

Miscellaneous

• Please make sure that all files (including .class and .html are readable).
• I didn't see very many citations, even though I know that many of you got some assistance from Andrew or me or each other. Remember, you need to cite such assistance.

Disclaimer Often, these pages were created "on the fly" with little, if any, proofreading. Any or all of the information on the pages may be incorrect. Please contact me if you notice errors.

Source text written by Samuel A. Rebelsky.

Source text last modified Tue Sep 23 10:26:19 1997.

This page generated on Tue Sep 23 10:30:26 1997 by SamR's Site Suite.

Contact our webmaster at rebelsky@math.grin.edu