Programming Standard for CS 115

The following is a set of requirements for all program assignments for CS 115. It is highly recommended that you check this page before turning in any assignment. The actual assignment may or may not mention all of these things; you are still responsible for them. Also read the Style Guide for more hints and requirements about how to format your program's code.

Your program is evaluated according to:

• Does it translate with no syntax errors?
• Was the electronic submission correctly done? file formats, etc.
• Correctness
  • Does the program work?
  • Does it meet the assignment specifications?
• Design
  • Is the algorithm correct?
  • Is it clear?
  • Is it efficient?
• Testing
  • Normal cases
  • Boundary cases
  • Error cases
  • Test cases clearly labeled
• Style Documentation Standard
  • Documentation
  • Layout of the code (indentation, spacing)

File Formats
Files to be turned in will have specified formats (.txt, .py, .doc, etc.). Please make sure your files are the correct formats.

If you submit files of incorrect formats, as soon as they are detected, you will be notified by email (the address that we have from the class mailing list). You are allowed to resubmit files - please submit the WHOLE assignment again. But you will be penalized as "late" if it is past the due date. It could cost you half or more of your program grade! You can create text files either with Notepad, or the editor in Python IDLE, or even MS Word if you save it in the correct format. If you have questions, you can show a file to any TA, preferably before the deadline, and they will tell you whether it is in the correct format or not.

Header Comments

You must write a header comment (prolog) at the top of your program that states:

• the author's name and email address
• the author's section number
• Any REFERENCES to assistance received by the author, whether from the partner, a TA, the Lecturer, class materials, the Internet.
• the purpose of the program (this may be a couple sentences or it may be a paragraph for the longer assignments)
• the date completed
• Preconditions: for the program, it is what inputs the program receives and where they come from
• Postconditions: for the program, it is what outputs the program generates and where they go to

Variables

Each variable must have a clear, meaningful name. Each variable must have a comment describing its purpose. In their comments, provide a short description of the role played by each.

Comments for Code Sections
Each section that performs a task should be preceded by a comment explaining the purpose of the section and the algorithm being implemented. Individual statements that are complicated should also be preceded by comments (or followed by a comment if it fits on the same line). A very long block of code that is part of a control structure should have a comment at its end that states which control structure it is a part of. The control structure may have scrolled off the screen when the person is reading the long block.

Function Documentation
Every function must have documentation, at its definition. You should be able to state the purpose of the function in a sentence or two. This sentence should be coherent and grammatically correct and it should involve all of the function's parameters. For example, "The function displays a square on the screen that is size rows high and width characters wide."

Each parameter should be documented. Any parameter that is passed by reference (mutable) (changeable) should be especially noted. Why are you changing it? Is it returning a value?

Local variables need documentation just like other variables. The return value of the function, if there is one, should be documented. Don't just say what type is being returned; say what the returned value means. "The function returns the average of the 4 parameters as a float" "The function returns the largest number input" "The function returns true if the data was in the correct format, false otherwise". See an example of function documentation.

Libraries
If you use a standard library file, with an import statement, you should document why you are using it. That is, you should state which functions you are going to call from that library. If you use a math function from the math library or some graphics functions from the graphics library, you should document that. The comment here does not have to be long, just a note of what you are using. It can help someone else who is trying to port your code to a different environment; they may have the functions in a different library, or may not have the functions available and have to write them. It helps you make sure you are not including code you don't need. If you don't have a reason for including a library, you probably don't need it!