CPSC 225 Programming 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.

Program Grading
Programming Standards

Program Grading

Programs will be graded based on the following criteria:

Functionality 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.	60%
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.	15%
Readability 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.	10%
Documentation 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, and the comments specified by the design recipe are included.	10%
Efficiency Problems are solved in a reasonably efficient manner, without an excess of convoluted logic or brute force code.	5%

Programming Style Standards

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)

One-letter variable names are rarely descriptive, though some common exceptions include using i, j, and k for loop counters, n for the number of things, and x, y, and z for coordinates of points. (But don't feel obliged to use these names if you can think of better ones!)
Try to use descriptive names even for loop counters e.g. name the counter after what is being counted.
Variable, constant, and class names are typically nouns.
Function names are typically verbs or short phrases involving verbs, with names of the form isSomething particularly appropriate for boolean functions. Examples: computeTotal, isEven, isLegalValue.
While C++ is case-sensitive (i.e. sum and Sum are different identifies), avoid names which differ only in case.

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

Variable and function names should start with a lowercase letter, with separate words indicated by capital letters. Examples: count, totalLength, computeCost. Function calls can be distinguished from variables in code because the name of the function in the call is always followed by parentheses.
Named constants should be all caps, with underscores to separate words. Examples: WIDTH, MAX_ENTRIES.
Class names should start with a capital letter, with new words indicated by capital letters. Examples: Player, BankAccount.
Instance variables should be named like variables (starting with a lowercase letter, new words indicated by capital letters), with a trailing underscore. Examples: count_, length_, diceSum_. Note: the book doesn't use this convention, but you should!

Commenting

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.