Introduction

You've been told, since your very first class, to write with good style. Some of you listened. Others found that good style was a pain, noticed that it wasn't always graded, and perhaps never bothered to learn.

The goal of this exercise is to make sure you practice good style. It should only take you several hours to finish this task.

This part is worth about 5 points of your total project grade, so you can decide its importance (i.e., you can decide if you want to skip this or do it, since you know how much it's worth).

As a testimonial, one former student said that his code was much easier to read once he began following some of the style tips in this exercise. Before, he never worried that much about his coding style.

Files Provided

The posting account contains a file called StyleExercise.cpp.

This contains a program that determines if one set is a subset of another. There are a list of tasks you're expected to follow, to improve the readability of the file.

When you're done, submit the modified StyleExercise.cpp with your entire tar file.

Task 1: Add a comment block to the top of the file

Here's the format.

// ************************************************************
//              Name:  Dion Blazakis
//          Filename:  StyleExercise.cpp
//           Project:  1
//       
//          Login ID:  bt214010
//           Section:  0101
//                TA:  Dave Levin
//          Date Due:  Sept 3, 2002
//      Date written:  Sept 1, 2002
//    Estimated Time:  About 2 hours
//
// Indentation Style:  GNU
//
//     Style exercise.
// ************************************************************

The header should contain the following information:

• Your name So we know who you are.
• The name of the file Just in case the file gets renamed
• Project The project number
• Your login ID Just to double-check who you are
• Section Easier to record grades if we know which section you're in.
• TA So you can practice writing your TA's name.
• Date Due and Date written. This is more useful to you if you like to keep old code from previous semesters. It's handy to know when you wrote the code.
• Indentation Style Which style you used to indent your code.
• Brief summary In a few sentences, explain what the file is.

All files (.h and .cpp) should have this information at the top.

Students often complain that it's tedious to write this header for each and every file. However, there's an easy way to avoid all the typing. Create a file that just contains the header above (you could call it, say, header.file) and copy it whenever you start a new file. You will find it saves time.

Task 2: Reindent the program

You can pick from one of four different styles to indent your code. K&R and Gnu are easily supported by emacs, however, any one of the four are acceptable in this project.

K&R style

Here's the K&R style (Kernighan and Ritchie, the guys who invented C). It's perhaps the most popular style for C/C++.

    if ( num > 3 ) {  // <-- open brace
       count++;  // body indented in
       num--;    // body indented in
    } // <-- close brace

Features

• The open brace appears at the end of the first line, with a single space after the close parentheses
• The close brace lines up underneath the "i" in "if"
• The body is indented at least 2 spaces (any number of spaces is fine, as long as it's lined up and is at least 2 spaces).

Allman style

  if ( num > 3 ) 
  {            // <-- open brace (not indented in)
     count++;  // body indented in
     num--;    // body indented in
  }            // <-- close brace (not indented in)

Features

• The open brace lines up with the "i" in if
• The close brace lines up underneath the "i" in "if"
• The body is indented at least 2 spaces (any number of spaces is fine, as long as it's lined up and indented in at least 2 spaces).

Whitesmiths style

    if ( num > 3 ) 
       {         // <-- open brace
       count++;  // body indented, aligns with brace
       num--;    // body indented, aligns with brace
       }         // <-- close brace

Features

• The open brace is indented in
• The close brace lines up with the open brace.
• The body is indented in, and aligns with the braces.

GNU style

    if ( num > 3 ) 
      {            // <-- open brace (indented in)
         count++;  // body indented in some more
         num--;    // body indented in some more
      }            // <-- close brace

Features

• The open brace is indented in
• The close brace lines up with the open brace.
• The body is indented in even more, from the braces.

Add a comment to the header that indicates what style you used

After Estimated Time, write the following:

// Estimated Time:  About 2 hours
// 
// Indentation Style:  K&R

emacs supports K&R and GNU style with the fewest problems, but you can pick any of the four styles. Try to use one of the four styles, even if that's not what you do normally.

Task 3: Indent the body of all functions

If you have code that looks like:

int main()
{
int x = 3;
if ( x == 3 )
  cout << "great" << endl;
x++;
return 0;
}

Reindent to make it look like:

int main()
{
   int x = 3;
   if ( x == 3 )
      cout << "great" << endl;
   x++;
   return 0;
}

The body of the function is indented in at least 2 spaces, and lines up. This makes the body appear a part of the function. emacs normally does this, if you hit TAB in the line (at least, when you edit code in a file ending in .cpp or .cc).

Task 4: Put a space before and after binary operators.

Instead of:

    if (x==y) {
      x=x+1;
      cout<<"ok"<<endl;
    }

Write

    if (x == y) {            // space added before and after ==
      x = x + 1;             // space added before and after = and +
      cout << "ok" << endl;  // space added before and after <<
    }   

Binary operators include:

• assignment operator
• arithmetic operators (+, -, /. *)
• logical operators (&&, ||)
• stream/shift operators (<<, >>)

Task 5: Put a space before semicolons.

Instead of:

    if (x == y) {
      x = x + 1;
      cout << "ok" << endl; 
    } 

Write

    if (x == y) {
      x = x + 1 ;  // add a space before semicolon
      cout << "ok" << endl ; // add a space before semicolon
    }   

This is an unusual style tip, but I think it's actually useful. I'm sure you've never seen this style idea anywhere.

So why do it? It's often difficult to see semicolons, because they are so close to the statement itself. This makes errors with semicolons hard to debug. You can literally stare at the code for a long time and not notice a missing semicolon. By adding a space, it stands out more, and should be easier to notice when it's missing.

Task 6: Add a space after comma.

Instead of:

    int x=2,y=3,z=4,w=5;
    z=foo(x,y);

Write

    int x = 2, y = 3, z = 4, w = 5 ;  // single space after comma
    w = foo(x, y, z) ;                // single space after comma

Again, this makes the arguments of a function easier to read, and makes the declaration easier to read, because it's less cluttered.

Task 7: Add comments.

Short comments can be added after the statement:

   w = foo(x, y, z) ;            // computes average

Longer comments should precede the body of code Having a // as the first and last line make the comment stand out more.

    // 
    // Finds the smallest value in the list, and updates it.
    //
    for ( int i = 0; i < size; i++ )
      {
        // body
      }

There are other forms of documentating style. In particular, Java has a tool called "javadoc" for extracting webpages from comments. While you do not have to do this here, you should read about it here

Task 8: Be consistent on spacing with parentheses.

Either have NO spaces just after the open parentheses or just BEFORE the close parentheses

   foo(x, y, z) ;   // Fine

Or one space just after the open parenthesis and one space just before the close parenthesis

   foo( x, y, z ) ;   // Fine

But not,

   foo(x, y, z ) ;   // NOT OK, space before close, but not after open

Nor,

   foo( x, y, z) ;   // NOT OK, space after open, but not before close

The last two versions do not create symmetric spacing with the parentheses.

Task 9: Factor out a function

Find some part of the code that would make a reasonable function, give it a reasonable name, comment it, and call it within the file.

Task10: Include the modified StyleExercise.cpp in your submission

Testing

1. StyleExercise.POSITIVE

   When you compile the program, and input redirect this file, the output should be:

   First set IS subset of second set
   

2. StyleExercise.NEGATIVE

   When you compile the program, and input redirect this file, the output should be: First set is NOT subset of second set

   Make sure your code compiles after making all the changes.

Web Accessibility

See the class syllabus for policies concerning email Last Modified: Fri Sep 13 20:11:45 EDT 2002

Web Accessibility