CSE 134A Project 3 grading rubric and comments

General comments

• The average score is 24.4 points out of 30.

Usability

Grade sections

1. (2 points) Simple, stable, and usable phone interface. In other words, it doesn't crash, and it is simple to understand and use.
2. (2 points) Clear directions. Clear directions were given on how to use the service. One example of bad directions is a site that immediately asks for a userid, without telling how to get a userid, or what the service is for.
3. (2 points) Handles user input well. Handles all your choices well. Particularly good if the site handles weird inputs, like "Michael Jackson".
4. (2 points) Organization of stories. Good organization of the information presented, and ease of moving among menus. Doesn't drone on in a story with no way to stop.
5. (2 points) Clean/usable web site interface -- web site exists, and roughly mirrors the functionality of the phone interface.

Canned comments

1. unclear navigation instructions
2. choices were unclear
3. something did not work as expected
4. simply exiting after servicing one request
5. phone interface crashes
6. "locking in the user", e.g. reading long stories without option to leave
7. interface is too linear
8. web interface insufficient
9. if there is a problem with the data (such as it doesn't exist), the system should identify this and not attempt to read it.
10. too many instructions
11. insufficient information provided
12. hard to understand the interface (words run together)

Code quality

Grade sections

6. (2 points) Comments (especially for difficult code)
7. (2 points) Clarity (variable names, code structure, flow of control)
8. (2 points) Modularity (using functions, and not reinventing PHP functions)
9. (2 points) Error handling (sufficient error checking)
10. (2 points) Organization (use only a sufficient number of files, avoid useless files)

Canned comments

1. Insufficient comments
2. Don't reinvent PHP functions
3. Unnecessary or too many files
4. Unclear flow of program
5. Modifying SQL tables inside code
6. Insufficient error handling
7. Insufficient decomposition of program into functions, or repetition of code
8. Don't use HTML comments to document PHP code
9. Should optimize DB access

• Most groups showed an improvement in comments. As mentioned before, it's very important to include block comments at the top of each file explaining the purpose of the file, as well as block comments for each function. Inline comments are also useful to help illustrate code flow. The advantage of including block comments for each file is that it allows someone who joins a project or takes over a bunch of code to very quickly and easily understand how all the files fit together.
• In regard to decomposition, there were several cases where code was unnecessarily repeated. Typically, if you find yourself writing basically the same lines of code for different parameters, this should indicate to you that a separate function would be appropriate. Sometimes functions can also be used just to logically break up otherwise enormous blocks of code. I also saw many cases where different php scripts were used to generate essentially the same page. Such files can easily be combined into a single script that takes some parameter.
• Error handling seems to still be a tough area for a lot of people. As mentioned previously, it is not a good idea to simply "die" in the middle of a script, and it is certainly not a good idea to use error-prone commands such as mysql commands with no error checking whatsoever. In industry, these errors are meant to let everyone know as soon as possible that something is wrong with the database and that it needs attention. If a failed query is treated the same way as a query that just returns no results, the database errors can go undetected for quite a while. Even in a screen-scraping context, it is important to report problems accessing the database not only because data may become outdated, but also because if the screen-scraper is having problems with the database, there is a good chance that all other interfaces may be having a problem as well.

Report

Grade sections

11. (2 points) Good grammar/spelling/language. You should use complete sentences, proper spelling and grammar, and avoid colloquial language and slang.
12. (2 points) Well-structured document. It should be easy to find information in the document.
13. (2 points) Addresses the major design decisions (usability, scalability, security, database design).
14. (2 points) Offers good solutions to the problems addressed, in a way that is understandable and repeatable.
15. (2 points) Technical correctness. Do not make statements that are incorrect!

Comments specific to your report are written on it in red ink.

Most of the significant deductions were for one of two things: ungrammatical or incomprehensible writing or failing to address the major design issues specified in the assignment handout.

• Use good grammar and spelling, and most of all, make sense. If your English isn't good, try to get someone whose English is better to proofread it and make suggestions. You'll learn this way.
• Cover all the points specifically mentioned in the project handout. For project 3, I quote: "explain all the important design decisions that you made ... you must address ... usability, scalability, and security. Other important design issues include, but are not limited to, portability and modularity." So address those. Use structure like headings and lists to help the reader find this important content.
• Don't tell the story of your project. Don't discuss ideas you had that turned out not to work or not to be feasible. Logically present and explain your important decisions so the reader can understand why you made them. If you compare different approaches, don't put one in the past tense (as in "we thought about X but then decided to do Y because ...").

For the next project, emphasis on grading the report will shift away from form and toward content. Here are mistakes to avoid:

• Discussing only low-level aspects of security/scalability/etc., without showing conceptual understanding of the central issues.
• Concentrating on superficial details such as file names, instead of justifying design decisions.
• Failing to explain advantages *and* disadvantages of design choices.
• Explanations of technical issues lacking logical coherence, and/or depth.
• Discussing topics in a scattered or rambling way.
• Wasting space on platitudes and generalities, instead of material relevant to this particular project.