CMPT
225 Coding Quality
This is a breakdown of what I'm expecting for
code quality, and a description of how it will be assessed in assignments.
Comments
Your code should be documented by comments,
sensible naming conventions, and by being cleanly written. For comments, I
expect the following:
Each function should be introduced by comments
explaining its purpose, the result of running the function (post conditions),
any requirements for the function to run correctly (pre-conditions) and a
description of its parameters
Major blocks of code within a function (such as
loops and decisions) should be introduced by a comment describing the purpose
of the block; this is not required where the function consists of a single
small block whose purpose is obvious. For example, a function to sum the
contents of an array might contain a single for loop and a return statement -
it is not necessary to comment that the loop is summing the contents of the
array (assuming that the function and its variables have appropriate names).
Single lines that contain complex expressions, or
whose purpose is not obvious should include comments to explain the purpose of
the line.
Unnecessary comments should be avoided - do not comment
every line in an attempt to ensure that you get these marks! For example, avoid
explaining the purpose of variables unless it is absolutely necessary (you
don't need to have a comment that explains that the age variable stores an age). You should assume that the person
reading your program understands C++ syntax, so this is unnecessary: x++; //increments x!
Rubric
Excellent (5) - follows the guidelines given above
throughout the entire program
Very good (4) - minor omissions of comments,
or some unnecessary comments
Good (3) - most functions and blocks
introduced with comments, but a number of missing comments
Mediocre (2) - a significant number of omitted
comments
Poor (1) - very few comments; for example,
only an incomplete description of each function
No comments (0)
Naming
Variable, function and class names should
clearly convey the purpose of the variable, function or class:
They should not be too short - however there are
situations where single letter variables are permissible; i is fine for an index in a for loop, x is fine for a parameter that represents the input to a
mathematical calculation that is not situated in a domain.
They should not be too long, they should be just
long enough to convey the purpose and no longer.
Avoid abbreviations that make it hard to determine
what word was being abrreviated.
They should be based on the context of the
program. If you are writing a program that records the age of two people having
variables called age1 and age2 is fine; however, if the program
records the age of a dog and a cat then cat_age
and dog_age are preferable.
You are not
required to follow any particular naming convention (for example Google's
style guide for C++, see the Wikipedia article on naming conventions for even more
examples).
Separating words in names by either underscores or
CamelCase is acceptable (for example, leftChild
or left_child are both OK), but
use one and not both.
Variable names should begin with a lower-case character,
and constants should be capitalized.
Rubric
Excellent (5) - follows the guidelines given
above throughout the entire program
Very good (4) - a few poor names
Good (3) - naming generally good
Mediocre (2) - naming inconsistent, some
identifiers are well chosen, others are not
Poor (1) - consistent use of unclear names
Most names unclear (0)
Indentation
The body of
each code block should be indented one position to the right of the previous
block.
There are various
conventions about where opening and closing {}s go. I have no particular
opinion on this (this is not actually true, but the point is that you won't
lose marks for not following my preference). One thing you should not do with
closing brackets is put more than one of them on the same line.
Rubric
Excellent (3) - all code correctly indented
Good (2) - a few incidences of incorrect
indentation
Poor (1) - inconsistent indentation
No indentation! (0)
Function
Design
In the majority of the assignments the return
types and parameters of functions will be specified for you. If they are not
then you should be aware of the following.
Functions should generally perform one (or possibly two
related) tasks, if a function is doing three or four poorly related tasks it
should be decomposed into multiple functions.
Functions that calculate values should return those
values, and not print them. If you want to print a value, print it from a
different function that calls the function that performs the calculation.
A function's input should be in its parameter
list, and its output should be its return value - don't use global variables!
Rubric
Excellent (5) - follows the guidelines given
above throughout the entire program
Very good (4) - a few incidences of poor
function design (such as insufficient decomposition)
Good (3) - function design generally good
Mediocre (2) - insufficient function
decomposition, and errors related to parameter lists and return types
Poor (1) - poor function design, use of global
variables instead of parameters
Very poor function design (0)
Class
Design
Like functions, most of the requirements will
be set out for you, however, you will still be marked on the following.
A class should be separated into header and
implementation files
Attributes should generally be made private and public
mutators (or constructors) should maintain class invariants (i.e. ensure that
attributes only contain valid values). Attributes that may contain any value of
their type may be made public.
Helper methods should be made private.
Classes that allocate dynamic memory should have
a copy constructor, a destructor and an overloaded assignment operator.
Object parameters should be passed by reference.
Calling objects and object parameters passed by references
should be made constant (const) if the function is not intended to change the
object.
Rubric
Excellent (5) - follows the guidelines given
above throughout the entire program
Very good (4) - some objects not made constant
when appropriate
Good (3) - multiple failures to follow class
design requirements
Mediocre (2) - multiple failures to follow
class design requirements
Poor (1) - poor class design, for example, no
use of constant and/or no private section
Very poor class design (0)
Assessment
Assignments will be assessed on
some or all of the above categories.
John Edgar (johnwill@sfu.ca)