Programming Style for Foundations of Computer Science

Function Decomposition (20%)

You must decompose your programs into smaller parts. One mainline won't cut it. This is one of the most common pitfalls of novice programmers. As a general rule of thumb, no function should consist of more than 20 lines of code. Yes, it's arbitrary, but think of it as a learning exercise; by having to fit within such constraints, you will come to appreciate what modular coding does for you, and when it is right to use bigger functions.

The decomposition process does not occur at the very end. Some of you have brought code to me to look at, promising that they'll split it into smaller functions, "when they're done". That's not the point--you don't do this just to make the program look pretty. You want to decompose the problem (and your solution, i.e. the program) starting at the design phase. By forcing yourself to design modularly (i.e., use functions) from the beginning, your program will go together faster, be easier to debug and easier to read. Think Legos© and Tinker-toys©: lots of small pieces, each easy to comprehend and debug. Plug them together and you can get great stuff!

As you write code, if you find a function becoming too large (too many variables, etc.), it's probably time to split the function into smaller parts.

For "toy" programming assignments like most of those of this course, you can get away with poor design technique (like not thinking modularly). But, believe me, you will fall down, *hard*, when you get to bigger programs.

Indentation(10%)

Follow the indentation style set forth in Astrachan's textbook. The basic rule is that whenever you use (or could use) curly brackets, you indent the code inside the brackets by 4 spaces (you may use a different amount, but you should be consistent.) Below is a part of one of the programs from Astrachan's textbook that shows proper indentation. int main() { string month; int days = 31; // default value of 31 days/month cout << "enter a month (lowercase letters): "; cin >> month; // 30 days hath september, april, june, and november if ("september" == month) { days = 30; } else if ("february" == month) { days = 28; } cout << month << " has " << days << " days" << endl; return 0; }

Identifiers (naming conventions)(10%)

• Variables and parameters: should be lowercase, except use uppercase letters to separate words within the identifier. So, if you wanted to name a variable "size of balloon", you'd use sizeOfBalloon.
• Global variables: same as for variables, but capitalize the first letter. Even better, you can prefix all such names with a "g". For example: gSizeOfBalloon.
• Constants: use all caps, and underbars to separate words. For example: SIZE_OF_BALLOON.
• Functions: as with variables, but the first letter is capitalized. For example: SizeOfBalloon().
• Class names: same as functions.

Comments

This is a biggy. There are several types of comments and these are explained below. Remember that the overall purpose of comments is to make your code readily understandable to a trained programmer (including yourself). It may seem wasteful to spend the time putting comments into your programs: it's not! The more you work with other folks' code, the more often you go back to work with your own, old code, the more you will appreciate comments.

File header comment(10%)

The top of each file should feature a comment that briefly outlines the Contents and purpose of the file. Also, specify the history of the file: the date of each modification and the name of the modifier. For example: #include <iostream.h> #include "CPstring.h" // Illustrates cascaded if/else statements. Calculates the number of // days in a month (specified as a string). // VERSION HISTORY: // Modified by Matt Evett, 5/23/1997 // Owen Astrachan 1/2/1996 int main() { etc.....

Header comments of class .h files(20%)

Like the header comments of other files, but more involved. You must describe the public interface. The header file for the balloon class, balloon.h, in the textbook presents a good example. A part of that file's header comment follows: #ifndef _BALLOON_H #define _BALLOON_H // class for balloon manipulation using simulated auto pilot // written: 8/29/93 (based on an idea of Dave Reed) // modified: 8/30/94, 12/29/94, 11/3/95 // modified: 5/23/97 by Matt Evett (changed header comments). // // Member function explanation: // // Ascend(int height): balloon ascends to height specified by parameter // in a sequence of burns. Each burn raises the // altitude by 10 meters etc....

Function header comments(20%)

Immediately above the definition of each function, describe what each function does. Pay particular attention to describing the parameters, especially if they are reference parameters that could be altered by the function execution.

Each function header must also contain a PRECONDITION and POSTCONDITION lines. The PRECONDITION comment specifies the preconditions that must exist for the function to execute correctly. Usually this is a relation or predicate that must hold on the parameters and global variables used by the function. The POSTCONDITION comment must specify what value the function returns, and any changes that will be made to reference parameters and global variables.

The following example is taken from craps2.cc:

bool GetPoint(int point) // precondition: 2 <= point <= 12 // postcondition: returns true if point obtained (winner) // returns false if 'crapped out' { int sum; do { sum = RollTwo(); } while (sum != point && sum != 7); return (sum == point); }

In-function comments(10%)

1. Local variables: each local variable should be declared on a separate line, with an in-line comment describing its purpose.
2. Subsection comments: for large functions (which should be rare, generally) you may want to place an in-line comment at the top of a subsection, describing what the code there does. Such comments should be indented with the code.
3. In-line comments: Knowing which lines to comment is one of the trickiest aspect of style. It's really more of an art, than a science. You should comment those lines of code that are not fairly self-explanatory. At the least, though, you must comment every flow-of-control statement (e.g. if, do, while, for, and function call.)

See code below, also taken from craps2.cc for some examples:

int main()
{
   int k;				     // Iteration counter.
   int gamesWon = 0;			     // Number of games won.
   int simulations =			     // Number of games to simulate.
     PromptRange("enter # games to simulate",1,1000000);

   for(k=0; k < simulations; k++)	     // For each simulated game....
   {
       if (WinGame())
       {
           gamesWon++;
       }
   }

   // After running all the simulations, we output the results....
   cout << "# of games = " << simulations;
   cout << " # won = "     << gamesWon << " = ";
   cout << double(gamesWon)/simulations * 100 << "%" << endl;
   return 0;
}