CIS 422 Project Grading

A total of 100 points is possible, but don't expect to get anywhere the total possible points --- the point guidelines include a lot of "headroom" for exceptional projects, with typical scores being 50-75% of the maximum in each category. Note that a single problem (e.g., inadequate documentation, or a progam bug) can cost points in more than one category. For example, if the documentation is not adequate for using a feature, you won't get credit for implementing that feature, nor will you get credit for documenting a feature that doesn't actually work (you may instead lose points for inaccurate documentation). Likewise, if a feature is implemented but cannot be used because the program crashes, you won't get credit for implementing that feature.

These are generic grading guidelines I use for software projects. For projects selected by the instructor, there may be additional specific notes on grading. See the project description for those notes.

50 - Functionality

Functionality includes features used by all categories of user. Often this includes administrative users (sysadmins, etc.) in addition to end users. Functionality also includes performance scalability.

Robustness: 15

15 absolutely bulletproof
12 robust under reasonable use
8 minor bugs, works well enough to be usable
4 major bugs interfere with normal use

Feature Set: 15

15 WOW! Exceptional
10 All needed features and some pleasant surprises
7 Adequate for the intended purpose
2 Missing features interfere with normal use

Ease of Setup: 10

Setup often includes system configuration. Note that setup documentation is also scored under documentation. Missing, confusing, or erroneous documentation may cost points in both categories.
10 a snap to install - on a par with highly automated installers
7 very good installation, on a par with very well-packaged open source systems. May require some sysadmin privileges or knowledge.
5 good installation overall; minor problems had simple and obvious solutions.
3 a little cumbersome, but installed without major problems
1 major difficulties installing
0 couldn't install

Ease of Use: 10

This category includes usabiliy for end users and for administrators. It is typically distinct from quality of documentation, but may include presence and usefulness of online help. Usability considerations for administrative users may be quite different than usability considerations for end users; both are considered here.
10 Couldn't ask for more
8 Quite usable, but could still be improved
6 Adequate usability, won't discourage normal use
3 Usability problems interfere with normal use
0 Unusable

25 - External/User Documentation

README.txt: 5 pts

5 very good README; complete overview with overview description and complete manifest including guide to other documents
3 adequate README, but either some inappropriate choices of what to put in or leave out minor organizational problems that make it less useful than it would otherwise be
2 README exists, but is misplaced, misnamed, or has flaws that limit its usefulness
0 README doesn't exist or is useless

Installation/Setup docs (complete? easy to follow?): 5 pts

5 Excellent docs for both common and uncommon cases
3 Adequate installation documentation, but could be improved (e.g., for less common cases)
2 Minor flaws or omissions, but still usable
1 Major flaws or omissions in installation documentation
0 Missing or completely misleading installation documentation

User Documentation: 15 points

Includes documentation for administrative and end-users.
15 really professional standards, on a par with the best commercial software
13 Good solid documentation for both tutorial and reference use, for all categories of user. Not quite professional standards, but very good for a short project.
11 Very good overall; could be better for some categories of user
8 Adequate overall, but some omissions or problems that could interfere with use.
5 Not very useful, due to flaws, omissions, or poor organization.
2 Barely useful at all.
0 No user documentation, or useless documentation

25 - Organization and Technical Documentation

Technical documentation and system organization are evaluated together. Good documentation can make a good design evident, and poor documentation can doom a good design to degradation over time, but good documentation cannot compensate for poor design. (See also: Change scenarios. )

Systems Requirements - 5 pts

5 Clear, complete, and well organized description of requirements, including rationale for what is included, what has been deferrred to the future, and (as appropriate) what has been excluded.
3 Adequate description of requirements. Some minor problems, but adequate as a guide to future developers.
0 Requirements statement is missing or inconsistent with the product; not useful to future developers.

System Architecture and Design Documentation - 12 points

12 Exceptionally well organized system, clearly described with clear breakdown of system into major parts; clear description of criteria for breaking into subsystems (e.g., it would be obvious where code for a new feature should go); and abstract understanding of program behavior. With a small amount of study I could easily port, extend, or modify the system. The system is organized in a way that makes it exceptionally easy to extend or modify, and each part of the system is specified precisely enough that it could be modified or replaced without studying other parts of the system. Anticipated changes (e.g., features or generalizations that did not make it into version 1) are clearly documented.
9 Good organization and design documentation, adequate for maintaining and extending the system. Most changes that might be anticipated would be easy, and the documentation of each part of the system is adequate. Some changes may not be quite as localized as one would like, but non-localized changes are reasonably simple, and the documentation is adequate to determine what must be changed. Documentation includes some anticipated changes for future versions of the system.
7 Adequate organization and design documentation, with some things that could be improved. Some changes may be more difficult to make than they should be.
5 Some major problems in design documentation, or some things that should be localized or easily configurable are inapropriately hard-wired in the application.
0 Technical documentation is inadequate, to the point that the only practical way to determine how to make a change is to read the source

Build support - 3 points

3 Simple, automated re-build of all artifacts including distributions from source distribution. Build support (e.g., Make or Ant configuration files) is well-organized and easily maintainable. Platform and site dependence is minimized and localized. It would be a snap to bootstrap a new distribution.
2 Good build support. Not quite as automated or complete as one would like, but adequate for a small project.
0 Build support is inadequate in some important ways.

Detailed Technical Documentation - 5 points

This can be any combination of external and internal documentation (e.g. JavaDocs), and applies to both conventional source code (e.g., Java) and to other artifacts such as Makefiles, page templates, etc. This is primarily an evaluation of usefulness of the documentation, not raw volume, and necessarily includes factors such as coding style.

5 Exceptionally well documented and readable... easy to read and modify.
3 Well documented, but could be better in places.
1 Inadequate documentation or serious impediments to understanding.
0 Seriously inadequate or misleading documentation.