Program Grading Guidelines

CSC 261 - Artificial Intelligence - Weinman

Summary:: This guide provides information on comments and format considerations used for grading programs.

Overview

This course features regular programming activities, as listed on the course schedule. While each exercise will have its own rubric based on the elements of the assignment, programming-based activities will feature several rubric elements in common. These items are measured on the following scale:

Excellent (Always): Four points; A. Demonstrates the criterion either without fail or a minor indiscretion; a complete or superlative exemplar.
Good (Usually): Three points; B. Misses one notable or two lesser instances of the criterion yet still demonstrates sound grasp of the practice.
Satisfactory (Sometimes): Two points; C. Features at least two positive demonstrations of the criterion or misses several important opportunities.
Passing (Rarely): One point; D. May have token, incomplete, or incorrect demonstrations of the criterion.
Failing (Never): Zero points; F. Completely overlooks the criterion.

Some of the criteria below may seem artificial and superfluous in a context where you are writing relatively small programs that an instructor has largely specified for you. You might even sensibly argue that, in following the composition principle of "writing for the reader," it is is petty or excessive to deduct for omissions that can easily be understood by the instructor. However, that argument overlooks the larger purpose, which is to develop good habits that translate to practice in systems of much larger scale. The importance of these elements increases exponentially with program complexity, and we hope to enhance your ability to "write for the reader" in that context as well.

In summary, these metrics represent important skills in the broader world of software development and maintenance. We measure them to help ensure you learn their primary characteristics.

1 Comments
    1.1 Begin files and functions with appropriate comments
    1.2 Describe main computations in comments
2 Structure
    2.1 Use clear function, parameter, and variable names
    2.2 Format programs for ease of reading and understanding

1 Comments

1.1 Begin files and functions with appropriate comments

Documenting before you write a procedure will help you plan and clarify the requirements of your implementation; it may even help you assess whether you need to refactor. For each function, documentation must include a sentence describing the purpose and contextualizing the purpose of the program unit in English. Furthermore, documentation must give preconditions and postconditions of each function.

Exemplars and Commentary.

1.2 Describe main computations in comments

Kernighan and Pike [KP] remind us:

Comments are meant to help the reader of a program. They do not help by saying things the code already plainly says, or by contradicting the code, or by distracting the reader with elaborate typographical displays. The best comments aid the understanding of a program by briefly pointing out salient details or by providng a larger-scale view of the proceedings. [emphasis added][KP, p. 23]

They also give us the following injunctions:

Don't belabor the obvious ("Comments should add something that is not immediately evident from the code, or collect into one place information that is spread though the source" [KP, p. 23])
Don't comment bad code, rewrite it ("When the comment outweighs the code, the code probably needs fixing" [KP, p. 25])
Don't contradict the code ("When you change code, make sure the comments are still accurate" [KP, p. 25])

2 Structure

2.1 Use clear function, parameter, and variable names

Speaking of named steps, those names should be sensible to your reader. We also remind you that you need to think beyond the scale of the program due this week. Your reader might be a programmer from another division, but it might also be yourself at a later time. Do not expect to remember what SMRHSHSCRTCH [KP, p. 5] means more than an hour after you write that down.

Like good writing, function names should indicate an action "verb" to promote understanding. An accompanying noun "object" in the name will also help.

In another analogy to writing, functions, parameters, or variables operating in analogous roles should be named analogously, the programmer's version of, "express co-ordinate ideas in similar form" [SW].

Clear parameter names are critical because they function as a bridge between two different scopes of execution. Avoid single letters; parameter names should suggest the role and semantics of each value entering the function. As the system scale grows larger, other programmers may only be familiar with a different corner of the system. Along with documentation, the published interface (parameter names) of your code will be key to understanding how to use it.

Generally variables are values local to a small function (cf and ). Yet these names too should clearly indicate their corresponding values. While no code is "self documenting," good names go hand-in-hand with understanding. They are the programmer's version of the writer's injunction to "avoid pronouns with unclear antecedents."

Global names of functions and variables should be particularly descriptive. Because they might occur anywhere in a program, their names need to completely evoke their meaning, regardless of context.

Loop variables representing an array index are often named i; that's not intrinsically bad. In fact, such conventional uses often benefit from short names, where long names would adversely impact brevity. However, nested loop variable names should indicate more about the meaning of each index. For example, r and c for rows and columns in a two-dimensional structure, t for a thread index, etc. When the corresponding array has a clear name, using mnemonic index variables (rather than i) can help you avoid errors.

2.2 Format programs for ease of reading and understanding

This criterion may encompass many abstract properties, but we can list a few concretely. Indentation, white space, and style consistency.

First, your program indentation should match the program flow. While most modern programming languages (Python excluded) care not a whit where your code appears because whitespace is irrelevant, the compiler is not the primary audience for your program. Human readers rely on indentation to help understand program flow with respect to functions, conditionals, and loops. Fortunately, your text editor will mostly do this for you automatically.

White space should help the human reader understand your programs at the expression, block, function, and source code level. After all, "white space is free", at least on screen. For grading, your programs will be printed (on paper, where white space is decidedly not free), so we take the comment with a grain of salt, admitting a measure of truth. Help your reader understand your code, but do not add separation beyond what is needed to aid clarity.

Practice a consistent style. When you write code from scratch, you may wish to practice one of the many existing "standard" coding styles. This course will not dictate a specific style, though your employers or open source projects may demand adherence to a particular style. When you are adding to or modifying an existing piece of software, match its style.

Finally, Kernighan and Pike [KP, pp. 6-8] give us a few additional style injunctions

Use the natural form for boolean expressions. ("Conditional expressions that include negations are always hard to understand" [KP, p. 6])
Parenthesize to resolve ambiguity
Break up complex expressions
Be clear ("the goal is to write clear code, not clever code" [KP, p. 6])
Be careful with side effects

We add one further concrete style guideline: Line must be no wider than 80 characters. This makes them easier to read both on screen and on paper. (Note: If running enscript on your program code produces the output "Xlines were wrapped," where X is some number, then your lines are wider than 80 characters and you should re-format your code with additional linebreaks.

Acknowledgments

In broad strokes, the contents of this rubric have been influenced by many sources. Criteria are adapted in part from an earlier version of Henry Walker's Program Style Summary and Checklist and used under a CC-BY-NC-SA 4.0 license. Marge Coahran influenced some of the style considerations and John Stone suggested expressing the learning objective as forming habits. Although cited when possible, many uncited ideas no doubt have been influenced by Kernighan and Pike [KP].

References

[KP]: Brian W. Kernighan and Rob Pike. The Practice of Programming. Addison-Wesley, 1999.
[SW]: William Strunk, Jr. and E.B. White. The Elements of Style. 1959.