Assignment Submission Guidelines
Projects Policies
Click on one of the policies below for details.
Hardcopy Policy
- Unless otherwise stated on the individual project spec, hardcopy for projects
is due the next class after the actual project is due.
- All hard copies should have a (readable: check the margins on your printout)
copy of the readme file on top, followed by the code for your main
class, followed by code for the other classes.
- Please print your hardcopy in a font big enough to be seen by the naked
eye.
- All hard copies turned in must be stapled together. Please do not hand
us a stack of loose paper.
Electronic Copy Policy
For your project you must submit a hardcopy and an electronic copy. Your
electronic copy will be turned in using the turnin script
on troi. If you do not have a troi account, you cannot turn in your project!
The following are some of the policies we have about your electronic copy.
Please read this carefully, as failure to follow these guidelines could result
in loss of points.
- Your project must run on troi.
MAKE SURE TO TEST YOUR PROJECT ON TROI! That is where the TAs will
be running it, and if it doesn't work, we aren't going to take the time to
debug it. IT IS YOUR RESPONSIBILITY TO MAKE SURE YOUR PROJECT WORKS ON
TROI!!! DON'T ASSUME THAT IT WILL WORK IF IT WORKED ON ANOTHER MACHINE!!!
Consider yourself warned. I can't give you points for a project that
does not run on troi. Some possible things that could make your project not
run on troi (things I've seen).
For more instructions on how to use JDK on troi, see here.
- Problems resulting from ftp
In JDK (i.e. every java but J++), a file must have the exact same
name as the class that is in it. Remember that in Unix, filenames are
case-sensitive. So a file named bob.java
is different than
a file named Bob.java
. Sometimes capitalization in filenames
will change when you ftp.
- Problems if you are using Microsoft J++ or JBuilder or another Java
compiler that is not JDK (if you are using Emacs, you are using JDK).
Sometimes Java compilers/development environments are not equivalent (J++
is notorious for this). In the end, your project must compile and run
under JDK. I would suggest developing in Emacs with JDK (see a TA in a
lab for help). If not, just make sure to periodically test your project
to make sure you're compatible.
- Problems with packages
The turnin script only turns in the files in the immediate directory you
turn in. It will not turn in any subdirectories! There have been some
problems with people using packages. I would advise against use of packages,
unless you really know what you are doing and can get it to work on troi.
Also, you need to make it be able to work within a single directory, which
I don't know if it is possible or not to do.
To compile using JDK, use javac. The syntax is javac < filename.java>.
Then to run use java. The syntax is java < name of main CLASS without
the extension> Please ask a TA if you need more help.
- Your electronic copy (what you submit on troi) should contain the following:
- All of your .java files (not ones distributed by TAs)
- All of .class files
- Readme file named readme.txt
- Any data files used for the project
Readme Policy
Readmes are for the TA's benefit who is grading your project. So they can
be useful to us, please follow the following strict guidelines. This makes it
easier for us to understand your program, which makes us more likely to be more
generous in giving you points.
- All readme files must be in text format. This means no Word files!!!
On a PC, you can create a file in text format by running Notepad (under Start->Programs->Accessories).
- Your readme file should be named readme.txt, not Readme.txt
not README.TXT and not p3readme1st.txt
- Make your readme easy to read. For example, don't print it out in a way
that letters just wrap around in between words.
- Readme files are for the TA's benefit, so they don't have to figure out
how to use your code and what or what not to expect from it. The better you
tell us this, the less time it will take us to grade your project, and the
happier we will be.
- Make your readme files short and concise
- Readme files should contain the following explicitly marked sections
with the following content.
- Header
- Name
- troi login name
- project#
- Completed - Which parts of the project you did do
- Not Completed - Which parts you didn't do
- Known bugs - (if we find bugs in your code that you did not
report, we will assume you didn't test your code well enough to find the
bug)
- Extra credit - what you did for extra credit (you will only
get points for what you mention in this section
- Autograder Compatability- This is a very important section!
If you believe that your code will work just fine with the autograder,
then just say that here. if not, then please tell us here how we
can verify what parts of your code are functional and which are not. Note:
it is your responsibility to help us be able to test your project and
to demonstrate to us (not in person, but through the autograder, throught
code, through your own tester program) that the parts of your code work
that you claim work. Of course, any program that does not work directly
with the autograder will lose substantial points.
Code Style Policy
Code style can really be thought of as 2 different categories. Organization
refers to how well you break up your program into classes, etc. How well you program
in an 'object oriented' fashion, etc. Documentation refers to how easily
your code can be interpreted by another human being. It deals with things such
as comments within your code, good variable naming strategies, general code readability
(such as tabs, etc.)
While perhaps not obvious now, good code style is very important if you want
to work on big projects or get a job with a company. Good code style allows
your code to be reusable and legible for years to come. While that's not so
important for a 171 project, if you work on a database system for a client,
they will want to be able to go in and understand (and perhaps modify) your
code in the future.
So, here are some guidelines for having good organization and documentation.
Code Organization
- Break your code up into reusable functions
A single method should usually not be more than 30 lines or so. If your method
is longer, ask yourself if there are 'functions' you can break it up into
that make sense.
- Practice good object oriented style.
Where it makes sense, try to analyze your project into the 'object' components.
Code Documentation
- For every close bracket you should put a comment that indicates what it
matches with. When your code gets big, it helps to be able to see what ends
where. Example
public static void main() {
blah blah blah();
} // end main
- Documentation is not putting a comment next to every single line
telling me what they do.
A lot of documentation can be done with how you name your variables and structures.
For example, please don't name your Queue q
and your Stack
s
. Name them for what they are for not what they are.
And please, don't call your main class Class1
!
- Make sure you name your functions for what they do, not part of what they
do. This is really confusing for someone (me) trying to read your code. If
your function is called
getInput
then it had better get the input
and that's it. Some people have named their function that and then it gets
the input, converts it to postfix and calculates the answer. Don't mislead
me with your names.
- Put comments about what the code is for not what it does. For example,
I had some code that looked like this
while (true) { // endless loop
blah blah();
blah blah();
}
Well, I'm smart enough to know already that while (true)
is an
endless loop. A better comment would be
while (true) { // loops through getting input until the user quits
blah blah();
blah blah();
} // end while
- INDENT!!!!!!! You will lose major points if your code isn't indented
well. This is crucial in program readability.
- Utilize line spacing to make code more readable. For example, in a method
you should probably have a blank line between where you are declaring your
variables and where the main code starts. Blank lines around big blocks (while,
for, if, etc.) usually looks good too. No spaces makes a program looked packed
and it is harder to see blocks of code. Don't stress too much about this almost
everyone has been doing this well.
- For each class and method, you should have a short blurb of comments explaining
what the method does/class represents (as opposed to how it does
it. Please put the comment after the method header, and indent
it in. This helps people be able to actually find a method. (i.e. if I'm looking
for your
main
, I don't have to fish through comments to finally
find it. Here's an example of how.
public double evaluatePostfix() {
// evaluates the postfix expression and returns the result
Notice you don't need to write a report for each comment. Make it short and
sweet. Remember, you are just trying to help people be able to read and follow
your code.
Adapted from Nate Blaylock's (a graduate student) CSC 172 Submission Guidelines.