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:

• A comment at the top of the program that includes
  • A brief description of what the program does
  • Program authors
  • Date or dates authored
• Concise comments that summarize major sections of your code
• Meaningful variable and function names
• Well-organized code
• White space to improve legibility
• Avoidance of large blocks of copy-pasted code

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.

• Be specific with your comments. Your comments should describe the intent of the code. What are you trying to accomplish with this piece of code?
• Do not make your comments (or code) too wide. Any line of comment or code that is over 80 characters should be split up over several lines. If many lines in your program do not print nicely, your program will be difficult to read.
• Do not overcomment! Overcommenting can make the program hard to read just as much as under-commenting. Do not comment every line. If your instructions are simple and clear, most people will understand them without your comments. If you think you need commenting, try commenting chunks of code under the same comment.
• Delete any extraneous code. You would not hand in an English paper with crossed out lines. Similarly, you should not hand in a lab with commented out code. Remove all code that your program no longer uses.

You should write comments for

• Programs and modules: At the top of each script/program/module, you should write your name, the date, and a brief description of what the script does. If you do more than the assignment requested, you should describe these "extra" features in the program under the class description. Sometimes it's hard to tell a bug from a feature.
• Variables and constants: In general, variables and constants should all have comments as to what the variable is used for. Frequently, several closely related variables or constants can be grouped together under the same comment.
• Functions and Methods: Above each function or method heading, describe what the function or method does. Do not describe the implementation details. You should also describe what each parameter means and what the return result means. If the code is simple, you do not need to comment within the body. If the body is complicated, add some comments to blocks of code to explain the implementation.
• Classes: Describe what your class represents, briefly, at a high-level.

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:

• Names that have nothing to do with the program are very bad names! Example: harry = "lemonade"
• Names that are not specific or descriptive enough are generally bad names.
• Try not to name objects sequentially. You should only do this when the objects are related in some way that is not otherwise expressible. Ex., data1 and data2 are not as good as firstName and lastName. if the data represent a user's first name and last name.

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: