Skip to main content.

Programming Style

Programming is not a dry mechanical process but an art form. Well-written code has an aesthetic appeal while poor form can make other programmers and instructors cringe. While having good comments or good variable names will not affect the correctness of your program, they make it much easier to read your program. It is important that others can understand your code so that they can modify your code if they have to. A significant component of your lab grade will be determined by your programming style.

Briefly, good programming practices usually include the following principles:

This page elaborates on these principles and serves as a guide to help you better understand what we are looking for when we look at your programs. As the semester progresses there will be steeper penalties for styling mistakes. Get into the habit of writing programs with good style from the beginning. After writing your lab be sure to look over your code and your style.

Commenting

Comments are extremely important. Take some care to write accurate yet concise comments.

You should write comments for

Note that we will not have all of these code "components" until later in the semester.

Blank Lines

Blank lines are used to delineate different areas of the code. There should always be a blank line between definitions of functions, methods, and classes. It is advisable to break up long method bodies and long declarations into logical pieces, usually headed by a descriptive comment of what the following block of code does.

Naming Literals

Do not use magic numbers in your method bodies. A magic number is a numeric constant embedded in code, without a constant definition. Any number except -1, 0, 1, and 2 should probably have a name that gives the number meaning. For example, rather than writing
toLower = chr(ord(capletter)-26)
associate a constant variable with the number:
NUM_ALPHA_LETTERS = 26
and use that variable in place of the number:
toLower = chr(ord(capletter)-NUM_ALPHA_LETTERS)

Names

You should always choose names that suggest the meanings of the things being named. If the purpose of a function is to remove all the blanks from a string, then a good name for that method is removeBlanks. If there is a variable of type int that is used to refer to the total number of message that have been sent, then a good name would be messageCount.

In general, follow the following rules of thumb:

By convention, constants are all capital letters; classes begin with uppercase letters; variable, function, and method names begin with lowercase, while uppercase is used to start new words in multi-word names. We also use an underscore ("_") to separate multi-word names.

Examples:

Variables
Good Bad
distance
velocity
acceleration
numLetters
num_letters
d
ve
A
n
num
Functions
Good Bad
drawPicture
squareRoot
computePrice
computeImage (less clear for this case)
sqrt
total


Portions adapted from style guides for Williams College's CS134 and Swarthmore College's CS21