University of Rochester Computer Science

Computer Science 171: Computer Programming

Home
Contacts
Labs
Lab Times
Lectures
Links and How To's
Projects
Programming Standards
(A.K.A. how to get a good grade on projects)
Schedule
Syllabus
Turn In (How to)
Workshop Times
WebCT

Programming Standards

Every program turned in to CSC 171 will be graded according to these standards. Programming standards are like style in natural languages, and like style in natural languages, the best way to learn it is to start by following strict guidelines. The intention behind both standards and style is to make reading easier. Since the programmer is the person who reads their code most, one of the biggest benefits of good programming standards is it makes errors easier to find. So, when writing a program, make sure that the program always follows the standards.



Electronic Copy
  • To Be Determined. Stay Tuned

Readme
  • All readme files must be in text format. This means no Word files!!!
  • 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... thus the higher your grade will be! :-)
  • Make your readme files complete, short and concise
  • Readme files should contain the following explicitly marked in sections
    • Name, troi login name, section, project#, etc.
    • If your readme does not have your troi login name we will not grade your project!!! This is the only way we can identify where your electronically turned-in code is!
    • Which parts of the project you did do
    • 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
    • How to run the code on troi (name of main class, command line parameters, runtime commands, etc.)

sample readme.txt


Hard Copy
  • There will be no turn in of hard copy for this class unless previously specified.

Organization Points

The 40% of your grade that is classified as "documentation" is actually broken down into 2 parts of 20% each: documentation and organization. Organization deals with how you choose to break up your project into classes, methods, etc.

Since organization is 20% of your project grade, it's a good idea to follow some tips.
  • I can't believe I have to say this but modularize your code!!!! This is a very very very serious problem. If you don't understand modularization or need help please come see a TA before it's too late! You will not survive Computer Science writing code like that, much less get a decent job afterwards. This may seem harsh, but it really is for your own good.
  • Practice good object oriented style.

Documentation Points

Documentation is another 20% of your grade. Documentation deals with things like naming of variables, methods, and classes, comments, and general program readability.

Documentation is really boring and annoying when you are coding a small assignment for class. When you work for a company that is writing a huge project with lots of people, it's absolutely necessary. Someday, someone will need to go in and look at your code and figure out what the heck it's trying to do. Please try to make their life easy. Companies want more than just someone who can code. They want someone who can code usable code. And, you never know, the person going back in 2 years and looking at your code may even be you. And trust me, even you will not have a clue what you were thinking at the time.

  • 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 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 getInput and then it gets the input, converts it to postfix and calculates the answer. Don't use misleading names.
  • Put comments about what the code is for not what it does.
  • 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.
  • 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.
  • 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 course web page of Fall 2004.
Updated 07-Sep-2003 16:48