Programming Fundamentals Computer Science 115 Fall 2004

Main | Syllabus | Grading | Programming Style | Honor Code

A PROGRAMMING STYLE GUIDE FOR THIS COURSE

This is the programming style guide for Computer Science 115. Part of your grade on labs and projects will depend on how well you follow these guidelines, so keep a copy handy, or remember where you can find it online!

THE BASICS OF GOOD DOCUMENTATION

The key to writing good computer programs comes in several pieces. Obviously, the design and correctness of the program itself is an important part. However, a part which is equally important is the documentation. We never write programs in a void; we are always part of a larger community, whether that community involves fellow students, professors in a programming course, or co-workers in a future job. Almost always, there will be someone who is going to have to read this program after you have completed it, and that someone is going to have to be brought up to speed on what you were trying to do and how you were doing it. That someone could be you; you would be surprised how hard it is to remember how a program was written only a few weeks after you put it aside!

This is why most (if not all) modern computer programming languages include some way to provide documentation alongside your program itself. This documentation is ignored by the computer, but any human reading your program will be thankful for it.

When you provide documentation for any program, you should keep the following factors in mind:

• Audience: Who is going to need to read this program in the future? Just you? Your professor? Your classmates? Some unknown future programmer?
  
• Precision: Once you have figured out what the audience of this piece is, determine what details this audience needs to have in order to understand your program. Do not be vague about anything this person would need to know about; similarly, do not include information on every single detail if that person does not need that information.
  
• Correctness: Make certain that your documentation actually tells the truth about the program! If you make any changes to the program, update the documentation to fit. Always test any claim you make.
  
• Completeness: Do not document only one part of your program, and then leave large parts of it undocumented. Make certain you cover everything that the audience needs to use it for, or might wonder about.

The rest of this guide goes into specifics on the expectations regarding the form your documentation should take.

• Header Comment: This comment occurs at the top of every source code file and every header file. It should always include your name, the name of the file, the date you began working on it, and the most recently modified date. If the file contains the main (or all of the) source code for the program, it should include information about what the purpose of the program is, what input it expects, and what output it produces. If the file is a supporting file, it should discuss what that particular file adds to the program as a whole (for instance, a file defining a C++ class and its methods should discuss the objectives of the object class you are defining). It should also include your statement that you have abided by the Wheaton Honor Code:
  
  Examples:
  
  //============================================================
  // Lisa Michaud
  // COMP 115
  // Started: October 13, 2003
  // Last Modified: November 5, 2003
  //
  // HoopyFrood.cp : A program to display to the user random
  // and witty quotes from the Hitchhiker's Guide to the Galaxy.
  // Requires no input, and outputs text to the screen.
  //
  // I have abided by the Wheaton Honor Code in this work.
  // - Lisa N. Michaud
  //============================================================
  
  //============================================================
  // Lisa Michaud
  // COMP 115
  // Started: December 8, 2003
  // Last Modified: December 20, 2003
  //
  // Towels.cp,.h : Defining a class for the 'towel' object,
  // used in the HoopyFrood program to provide both protection and
  // shelter.
  //
  // I have abided by the Wheaton Honor Code in this work.
  // - Lisa N. Michaud
  //============================================================
  
  
• Function Comment: At the beginning of each function you define, you should have a comment listing the name of the function, your name, the date you wrote the function, and a description of what the function does. In particular, describe what the input to the function is, what the output is, and what (if any) side effects the function may have on its parameters.
  
  Example:
  
  //============================================================
  // AirConditioner()
  // Author: Lisa Michaud
  // Date: October 13, 2003
  //
  // Desc : Takes in warm, humid air, removes the moisture, and returns
  // cooler, drier air.
  //============================================================
  
  
• Internal Comments: Inside functions, you should comment both the declarations of variables and any major parts of a function that are not entirely self-explanatory. You do not need to comment every line, but comment sections of a function so that the reader can see what each part does.
  
  Example:
  

   
  	  int id;           // the ID number of a person in the DB
  	  int SSN;          // the person's social security number
  	  
  	  // determine if the person has guessed the correct number
  	  if ( number == 42 )
  	  	cout << "YES!!"
  	  

INDENTATION AND OTHER WHITESPACE

While C++ does not require you to indent your code, nor in fact to include any whitespace at all if you wish to smush all of your statements together on one line and never use the spacebar, the return key, or the tab key, it is a necessity for readability that you use all of these three keys in good amounts. Code surrounded by curly brackets (braces) sould always be indented a minimum of 3 spaces from the surrounding code. Other whitespace should be used as you see fit to space out your code and make it easier to follow.

VARIABLE AND FUNCTION NAMES

It goes without saying that variable names such as x and y are not very informative, and should not be used for many purposes other than as loop indices. Do not be stingy with the names you give to your variables, functions, and object classes. Do not be cryptic, either. Allow them to be descriptive. Even when you comment their declarations, a reader will best remember that identifier's purpose if the identifier is easy to read.

FUNCTION STRUCTURE

A wise man once said: "A function should never be larger than one screen." Functions that stretch on for hundreds of lines are not following a modular structure; they should be broken down further into smaller functions. Screen sizes vary, but this general guideline helps give you a heads-up when a function is getting out of control.