COMP 105
Alice Documentation and Coding Standards
(Loosely based on the Kalamazoo College Computer Science Program Style Guide and Documentation Standards)
Last revised: January 2006
Synopsis
Programming is a form of communication. A program that is difficult
to read and maintain is not very valuable, even if it happens to work.
The purpose of this document is to provide some guidelines that will
help you to create well documented and well organized Alice programs.
Comments
Comments allow us to write in natural language to clarify the intent of
the program. Comment programs internally with clear, coherent statements
in concise English, using good grammar, punctuation, and spelling.
Your Alice program should always include the following comments:
- The main method in your program (by default this is called "World.my first method") should begin with a block of comments that include the following information:
- Your name, the date, and the name of the assignment.
- A brief description of what the program does.
- Every method and function in your code should include a brief
description of its purpose. The emphasis here should not be on
what the code does, but why it does it. For
example if you have a method that moves a character up and down three
times, the following comment will not be useful: "This method moves the
character up and down three times." A better comment might be: "This
method animates the character's celebratory dance, which he performs
whenever he makes a goal."
- Any segment of code in your program that is complex or potentially
confusing should be commented.
Programming Style
Even more important than good comments is good programming style. A
meticulously commented program that is poorly organized is much more
difficult to understand than a well organized program with very few
comments. Learning good programming style takes practice, but the
following guidelines should get you off on the right foot.
Naming
- Names should begin with a lowercase letter. A name that includes
multiple words should use upper case letters to show word
boundaries. For example:
moveCarToLight. The exception is
Class/Object names which should begin with a capital letter.
- Names should reflect the purpose of the named entity. A method
that moves a rabbit through a door should be named
moveThroughDoor or moveBunnyThroughDoor. It should
not be named method1 or ralph. Similarly, variable
names should reflect the purpose of the stored value. A number
variable that stores the speed of a ship should be named
speed. It should not be named num or
tmp.
- Never use spaces in names! Alice is nearly unique in the history
of programming languages for allowing the use of spaces in names. THIS
IS NOT A GOOD THING. Names should include no spaces or other special
characters. Restrict yourself to letters and numbers.
Organization
- Keep methods and functions reasonably short. Long blocks of code
are difficult to read, and can usually be broken up into multiple
methods.
- Avoid the use of constant values in your code. As a rule of
thumb, if a number appears more than once, it should probably be
stored in a variable. For example, if your animation includes a
character that always moves at three meters per second, every move
command should not be explicitly set to 3. Instead, create a
variable named
characterSpeed, set that variable to
3, and use the variable as a parameter for every move command.
That way, if you decide to change the character's speed, you only
need to change the value in one place.