CPSC 225 Intermediate Programming Fall 2006

CPSC 225 Programming and Journal Standards


There is much more to a good program than just having it run correctly - while correct functioning is critical, it is also important to create a well-organized, well-documented, and easy-to-understand program. Why? For starters, it is much easier to create a correctly-functioning program and to verify its correctness if the program is organized and its logic is clear. Furthermore, the initial development is only a relatively small portion of the life cycle of most real software - fixing bugs and adding new features may go on well after the initial product is shipped, and may be done by people not involved in the original development.

Programs will be graded based on the following criteria:

The program works correctly and meets all of the specifications, including proper formatting of the output. Error-checking is thorough, and errors are handled in an appropriate manner. A program which does not compile will receive an automatic 10% deduction.
Design and Reusability
The code is logically and appropriately grouped into functions and classes, and reasonable decisions were made about how to implement the program's functionality. The program's functionality could be modified or extended in reasonable ways without requiring major rewriting of the program. Parameterized modules are used instead of repeating very similar chunks of code. Routines could be reused in other programs.
The code is well-organized within each module and is easy to follow. Overly awkward constructs are avoided. Naming and whitespace conventions are followed consistently.
The documentation is well-written, clearly explains what the code is accomplishing and how, and is of an appropriate quantity. Commenting conventions are followed consistently.
Problems are solved in a reasonably efficient manner, without an excess of convoluted logic or brute force code.

Standard Conventions

One aspect of creating reading programs is to follow standard conventions for naming and formatting. There are a number of variations and you will see different styles used in different places. The following outlines the conventions we'll be using in this course.

Naming Conventions

Filenames should be descriptive, should end with .h (header files) or .cc (implementation files), and should generally be all-lowercase letters. If a header file is named something.h, the implementation file should generally be named something.cc.

All C++ identifiers must have descriptive names. Some general guidelines: (though not hard-and-fast rules)

Identifiers used for different purposes should be easily distinguishable. A common convention (and the one used in this course) is the following:


Files: Every file should contain a comment with your name and a brief description of what is in the file and its purpose. (Everything in the file should form a logical unit, so this description can be brief.) Exception: the description can be omitted for .cc files which implement header files.

Programs: Every program should have a comment describing what the program does, what input it expects, and what output it generates. This typically goes with the file comments of the file containing main.

Classes: Every class declaration should have a comment describing the purpose of the class immediately before the start of the declaration. (For a file containing only a single class declaration, the description of the class can be grouped with the file comment.)

Functions/Class Methods: Every function and class method should have a comment describing the purpose of the function/method, the meaning of each of its parameters, and the meaning of its return value (if any). The comment should also include pre- and postconditions, as appropriate. Information which can be read from the function definition itself should not be repeated in the comment e.g. something like "n is an integer" (when the parameter declaration is int n) is redundant and unnecessary in the comment. Ideally, the function/method comment should go before both the function prototype/method declaration and the implementation but it is acceptable to only comment the prototype/declaration.

Variables/Constants: All variables (including instance variables) and constants should have a brief comment describing the purpose of the variable/constant, including any other information relevant to its proper use. These comments are typically short and can occupy a partial line after the declaration; if the comment would wrap onto a third line, then put the comment on line(s) by itself immediately before the declaration.

Other: It can be useful to comment sections of code within a function body, particularly if there are several distinct steps to accomplish the task. Within-function comments should also be used if there is a tricky section of code - perhaps the logic is a bit tricky, something is done in a certain way for some reason, or making a change in one place requires some other change. Comment all of these things to help you organize your thoughts, and to make debugging and maintenance easier.

Whitespace Conventions

Indentation should be used to indicate the block level of each statement - the bodies of classes, functions, conditionals, loops, and block statements are indented one additional level beyond the current indentation. Emacs will auto-indent correctly (incorrect indentations are generally due to syntax errors).

Semi-colons (;) and both open and close curly brackets ({ and }) should generally be followed by a line break.

Line breaks should also be used to split up long statements so that no text goes beyond 80 columns wide (the standard width that fits on one line of a printed page). Emacs will tell you the column number of the cursor so you can keep tabs on how long your lines are (the easiest is just to set your emacs window to 80 columns wide). Line breaks can go anywhere except in the middle of an identifier, keyword, multi-symbol operator (like between the < and = in <=), or string. To decide on a good place, try to avoid breaking up chunks of the statement that are closely related. After an operator or a comma are often good places. When you break a statement into multiple lines, use indentation to help the reader follow the statement. The indentation should generally be used to line up text with similar text on the previous line of the statement, though there are exceptions to this when it would result in very large indentations. Emacs will often indent things reasonably, but not always. Use your judgement as to what is most readable.

Blank lines should be used to group tightly-related chunks of code and separate less-related parts. Within a function, blank lines can be used to group different parts of the function's task - e.g. put a blank line between a set of variable declarations and the code that uses them, or between the code that reads the user's input and the code that processes it. There aren't hard and fast rules, but remember that the goal is to help the reader understand the structure of the program.


Your journal will have two major components: program reports and reflections.

Program reports are a bit like lab reports. For each homework assignment, your program report should contain the following elements:

Reflections are more free-form - discuss something you learned or something you have questions about. This might be something from the homework assignment, or from other course material. Expect to write at least one paragraph for each reflection.

You should add to your journal often - write things down as you think about them, rather than waiting until just before it is due to catch up on a backlog of entries. This is true of program reports as well!

Journals will be graded on the following criteria:

Description, Approach, Problems
These elements of the program report are addressed in sufficient detail. The program description accurately and completely describes what the program does. The solutions described for any problems encountered are correct.
Note that while you may receive feedback on your approach to the problem, you will not be graded on whether or not it is a "correct" approach (there are many valid approaches).
The discussion of the design reflects an understanding of program design principles. Design decisions are reasonable and are justified.
The discussion of testing reflects an understanding of testing principles. Test cases are thorough and appropriate.
There is at least one new reflection since the last time the journal was submitted. Reflections are thoughtfully considered and are of sufficient length.
Writing & Presentation
The writing is clear and organized. Correct grammar and spelling is used. The formatting is reasonable. The journal is typed (preferable) or legibly hand-written.

Valid HTML 4.01!