ECE 417/617 Elements of Software Engineering

Spring 2006

In this course students will learn to build high-quality, reliable, and extensible software systems that are too large for a single programmer.  Emphasis is placed upon good programming practices (object-oriented design and clean, well-documented code), teamwork skills (planning, communicating, and interacting), and bringing the project to completion (testing and verification).  A semester-long project complements the theory with practice.

Syllabus

Announcements

• 1/11/06: Welcome!
• Groups for milestones 1 and 2:  groups12.csv
• Groups for milestones 3 and 4:  groups34.csv
• Groups for milestones 5 and 6:  groups56.csv

Schedule

Week	Topic	Assignment
1	introduction / overview	hw #1 (1/20)
2	C++ and Visual Studio IDE	milestone #1 (1/27)
3	More C++, object-oriented programming, and CVS	milestone #2 (2/8)
4	Software life cycles
5	Software process and modeling (UML)	milestone #3 (2/17)
6	Project management
7	Agile methods	milestone #4 (3/3)
8	Requirements
9	System design	milestone #5 (3/17)
10	[Spring break]
11	Testing	milestone #6 (4/3)
12	Risk analysis
13	User interfaces	milestone #7 (4/14)
14	Formal methods
15	Ergonomics	final system (4/28)

Other dates:

• 4/21:  Report due, oral presentations in class
• Quizzes (throughout semester)
• Final exam:  5/4, 8:00 - 11:00

Textbook and Resources

Recommended textbooks:

• Bjarne Stroustrup, The C++ Programming Language, Addison-Wesley, 2000.
• David Gustafson, Schaum's Outline of Software Engineering, McGraw-Hill, 2002.

Additional software engineering resources
 

1. Condensed Crash Course on C++
2. An Intro to Concurrent Versions System (CVS)
3. GUI-Based Programming
4. System Design
5. Brief Overview of UML Diagrams with a Simple Example
6. Design Patterns
7. User Interface Design
8. Software Life Cycles
9. The Cathedral and the Bazaar:  A Look at Open-Source
10. Repetitive Strain Injury (RSI)

Here is one example of the type of visualization we would like to be able to do:  http://www.itl.nist.gov/div898/winds/homepage.htm

Project organization

Students are divided into groups, and the groups work in parallel to develop rival applications that meet the desired specifications.  Including the final demo, there are eight biweekly milestones throughout the semester.  For each milestone, the job of each group is to write clean, maintainable code that meets the specifications in a robust manner.  The students are initially divided randomly into groups of three people each, then they are randomly reshuffled after Milestone#2 into new groups of four people each, then after Milestone#4 they are randomly reshuffled again into groups of six people each, then after Milestone#6 they are randomly reshuffled into groups of eight people each.  Each milestone is treated like a public release, so that (because this is an open-source project) each group is allowed to incorporate whatever code it desires from any other group.  For example, for Milestone#3, a group may use code that other groups checked in for Milestone#2; in fact, a group may scrap their entire code base completely and start with another group's code, if they so desire.  No code sharing, however, is allowed within a single milestone.  

Each group is responsible for dividing up the work among its members, scoping the work to be done, and keeping track of the accomplishments of each member as well as the accuracy of the time estimates.  For each milestone the group should submit the source code itself (via CVS); a compiled executable (via email to both the professor and the grader); a system design document (hardcopy and CVS); and a summary of the work done including a detailed task list with the responsible individuals, estimation times, and completion dates (hardcopy and CVS).  The latter two documents should be named sysdesign?.doc and summary?.doc, respectively, replacing the ? with the milestone number. (The file extension will depend upon which word processor you use; any reasonable choice is acceptable.)  When checking in code, be sure to check in all .cpp, .h, .dsp, .dsw, and .rc files, along with the res directory that contains .ico and .rc2 files.  The .ico file is binary, while all others are text-based.  Do NOT check in all the other files that Visual Studio creates automatically, such as .aps, .clw, .ncb, or .opt.  When in doubt, check out your code to a new temporary directory and verify that it compiles and runs.

Coding conventions

Writing code that compiles and runs is not enough.  An important part of software engineering is writing code that is also easy to read by other programmers, not only those in your team but also those whom you've never met.  Since we will be reading each other's code,  it is important for us to have an agreed-upon set of conventions.  Since the conventions themselves are somewhat arbitrary, the following list has been compiled using some of the more common approaches adopted in the industry.

• Spelling and syntax:
  • class, struct, namespace, function, method:  InterCaps style (first letter of each word capitalized), also known as CamelCaps
  • typedef:  same as class
  • local variables, function parameters: all_lowercase_with_underscore_between_words
  • member variables of a class:  same as local variables, but with 'm_' prefix
  • macros, enums:  ALL_UPPERCASE_WITH_UNDERSCORES_BETWEEN_WORDS
  • global variables (avoid these of course):  same as local variables, but with 'g_' prefix
  • private methods:  iInterCaps (intercaps but with a leading underscore i)
  • filename (if one file per class):  ClassName.[h,cpp]
  • braces { }:  in the same column (C++-style), not opening brace at end of line (Kernigan&Ritchie C-style)
  • number of spaces in a tab:  2 (but insert spaces, not tabs!)
• Comments and parameter passing:
  • Functions that do not modify the member variables of a class are declared const
  • Function parameters that are not modified (except native types) are declared with const&
  • Function parameters that are modified are declared with a pointer (*) and come after all the inputs
  • Functions local to a file are enclosed in an unnamed namespace to keep its linkage internal to the file.  Like private methods, these follow the iInterCaps style.
  • Just before each class declaration, a comment briefly describes the purpose and functionality of the class, any non-obvious peculiarities, and the author's name in JavaDoc / Doxygen format (starts with two asterisks, keywords start with @)
  • Each header file starts with #ifndef #define, and ends with #endif;  double-underlines lead and trail name of file in ALL CAPS WITH UNDERSCORES; Example:
    #ifndef __BLEPO_IMAGE_H__
    #define __BLEPO_IMAGE_H__
    ...
    #endif __BLEPO_IMAGE_H__
• Licensing:
  • At the top of each file that you write or modify (do not worry about automatically generated files that you do not touch), include the GNU GPL license:
    /*
    * Copyright (c) 2006 Clemson University.
    *
    * This program is free software; you can redistribute it and/or modify
    * it under the terms of the GNU General Public License as published by
    * the Free Software Foundation; either version 2 of the License, or (at
    * your option) any later version.
    *
    * This program is distributed in the hope that it will be useful, but
    * WITHOUT ANY WARRANTY; without even the implied warranty of
    * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
    * General Public License for more details.
    *
    * You should have received a copy of the GNU General Public License
    * along with this program; if not, write to the Free Software
    * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
    */
     

Example:

   /**
    This class keeps track of time.
   
    @author Ima Coder
   */
   
   class TimeManager
   {
   public:
       typedef int SecondType;
       TimeManager();
       double GetTime(int day, const TimeStamp& another_time);
   private:
    double m_day_of_the_week;
   };
 

Among the many standards on the web, Todd's very extensive and helpful C++ coding standard is similar to that above and also contains some insightful points about software engineering in general.  Wallach has a shorter coding convention list.  Lott maintains an extensive list of conventions, some of which are quite extensive :).   Linus Torvald's conventions for the Linux kernel makes a fun read, though it's geared toward C rather than C++.  And, for something completely different, don't forget to check out Microsoft's Hungarian notation.

CVS (concurrent versions system) instructions

To start using CVS through WinCvs, either follow Saurabh's "Intro to WinCvs" or do the following:

Your password will be emailed to you.  If you wish to change it, please email a different password to the grader so we can put it into the CVS passwd file.  Note:  CVS has poor security, so do not use an important password for this project.  Instead, send something that you don't mind having compromised.  Once you have done these steps, then

1. Download and install WinCvs/MacCvs/gCvs on your development machine
   (Or, if you're working on a Clemson DCIT Windows machine and do not have permission to install software, then copy the file wincvs-postinstall.zip (the resulting install directory) to your U: drive and unzip it)
2. If you're not using Microsoft's Windiff, then download and install an external diff program (e.g., WinMerge for Win32 or xxdiff for Unix)
3. Start WinCvs (wincvs.exe)
4. Click Admin.Preferences
   1. Under General tab,
      1. Set CVSROOT to yourid@cvs.ces.clemson.edu:/pub/cvsprojects/ece417
         (Replace yourid with your student id)
      2. Set Authentication to "passwd" file on the cvs server
   2. Under WinCvs tab,
      1. Enter path of external diff program, and click checkbox (For Windiff, go to C:\Program Files\Microsoft Visual Studio\Common\Tools\windiff.exe)
      2. Set Home folder
5. Click Admin.Login and type your password (this will store your password locally in your Home folder/.cvspass)
6. Click Create.Checkout module
   1. Enter module name:  name, where name is defined below
   2. Enter local folder to checkout to
7. Now CVS is ready for you to add your own files, modify them, etc.!  For reference, see the on-line CVS Cederqvist manual or Redbean manual

Alternatively, if you would prefer to just use the command-line version,

1. Download and install the cvs client on your development machine
2. Use a text editor to create a ~/.cvsrc file that contains a single line that looks like this:
   cvs -d :pserver:yourid@cvs.ces.clemson.edu:/pub/cvsprojects/ece417
   (Replace yourid with your student id)
3. type cvs login at the command prompt, along with your password (this will store your password locally in your ~/.cvspass file)
4. cd to the directory in which you want to copy files from the repository
5. type cvs checkout name, where name is defined below
6. Now CVS is ready!  For reference, see one of the manuals above

Replace name with class/seebreeze (Spring 2006), or class/rootfly (Spring 2005).

For the grader: 

• To encrypt a password, use
      /usr/local/bin/perl -e 'print crypt("MyPassword","St") . "\n";'
  replacing MyPassword with the password you would like to encrypt.  (You may need to use /usr/bin/perl  if the above does not work.)
• To print a history of all checkouts and updates,  cvs history -x UO -a

Paper / Presentation

Each student will independently investigate some topic of software engineering. Topics may include, but are not limited to, methodologies, case studies, overviews, and/or tools. Students are required to write a short report (ECE 417:  at least one page with one reference; ECE 617:  at least three pages with three references) and give a brief oral presentation in class.  Some suggested resources are

• International Conference on Software Engineering
• IEEE Transactions on Software Engineering
• IEEE Computer Magazine
• Roger Pressman's Software Engineering Resources

Individual assignments:

• HW#1 (due Friday, 1/20): 
  • Write a C++ class called File with the following public methods: 
    • empty constructor --- does nothing but initialize private members appropriately
    • constructor taking a const char* --- opens a file for reading using the provided filename
    • void Open(const char*)  --- same as previous, but first closes the current file if there is already one open
    • void Close() --- closes the file if there is one open, otherwise does nothing
    • destructor --- same as previous
    • bool ReadInteger(int*) --- reads the next integer in the file separated by whitespace; returns a bool to indicate whether it was successful (0 indicates EOF, 1 indicates success)
    Privately, the class should own a FILE* and access the file using C routines.
  • Write a function int Add(const std::vector<int>& a) that adds all the numbers in a standard vector.
  • Write a Visual C++ console-based application that takes a single command-line argument, namely, the name of the file to open. When executed the program should open the file, read all the numbers in the file until the end of the file is reached. The program should print all the integers one after the other on stdout, after which it should print the total of all the numbers, the total being computed by the Add function. 
    • To create a console app, follow these instructions:  File -> New -> Project -> Win32 Console Application. Give it a name (Name the workspace userid_hw1, where userid is your Clemson user id) and keep the checkbox on "Create new workspace". Choose "An application that supports MFC." Now compile and run (Build -> Build ..., and Build -> Execute, or F7 and Ctrl-F5). Under FileView -> Source Files you will find the main cpp file.
  • Email the grader with the subject line "HW1" (without quotes).  The email should have the following files attached:
    • username_hw1_exe (This is the precompiled executable, but with the extension renamed so that it is not blocked by the email system). 
    • username_hw1_zip (This is a zipped version of your entire workspace -- with extension removed -- with everything needed to compile your code.)
    • all the source files that you actually wrote for the homework, attached as individual text files (there will probably be only one or two of these).

Group assignments:

• Milestone#1 (due Saturday, 1/28, by 11:59pm): 
  • Write a Visual C++ dialog-based application that allows a user to draw polygons on the window.  Single-click starts a new polygon or adds a point to the current polygon, and double-click ends the polygon.  When the mouse moves, the line from the last point to the mouse position should be drawn and updated dynamically.  It is okay for the color to be hardcoded, and do not worry about flashing on the screen.
  • To do this project, you will need to override the OnLButtonDown, OnLButtonDblClk, and OnMouseMove methods of the dialog class.  View -> ClassWizard.  Make sure that your dialog class is highlighted under "Object IDs".  Under "Messages", click on message (e.g., WM_LBUTTONDOWN), then click Add Function, then click Edit Code.  This will take you to the method in the cpp file to handle that message.
  • You will also need to draw lines on the window.  Use the CDC::MoveTo and LineTo functions.  (Search on MSDN for help if you need.) 
  • In CVS, make a directory (inside the directory of your group) called milestone1.  Check into that directory
    • Your code.  Include everything needed to compile your executable, but nothing else.  See above. 
    • Your Software Project Management Plan (SPMP), including your group name, group members, project organization, and work breakdown structure.  The work breakdown structure (WBS) should list all the work to be done for the milestone, with each task assigned to a specific person.  Time estimates and actual time should be indicated for each task, along with the person(s) who did the actual work.
  • In addition, each individual in the class should check in a file into their group's milestone1 directory a text file named userid.txt (replacing userid with his or her Clemson user id).  The text in the file is not important.
• Milestone#2 (due Wednesday, 2/8, by noon): 
  • Write a Visual C++ application that uses OpenGL to draw a 3D cuboid (a cube, except the sides may not be equal).  At each of the eight corners, draw a sphere.  Mouse movements should allow the user to rotate, translate, and zoom around the object.
  • The coordinates for the corners of the cuboid, as well as the radii of the sphere, should be read from a text file.  The file should have eight lines, one per corner. Each line should contain four numbers:  x, y, z, and radius.  The order of the points should be clockwise for the top face, then clockwise for the bottom face.  Here is a sample file:  cuboid.txt . 
  • Various sources to assist learning OpenGL for MFC / Visual C++ are available on the web.  One sample application that may help you is wed2.zip , available from this page. 
  • Use CVS to check in your code and SPMP into a directory called milestone2, as before.
• Milestone#3 (due Monday, 2/20, by noon):
  • Write a Visual C++ application called Seebreeze that allows a user to load files specifying the building dimensions, sensor coordinates, and pressure data.  The application should then display the building in 3D with the pressure data overlaid on the appropriate surface.  The user should be able to translate, rotate, and zoom around the building, and the user should be able to select between max, mean, min, RMS, and var using a drop down box (see MSDN help on CComboBox).
  • Here are the files that we have received from the client:
    • The coordinates and normalized pressure data for all 290 sensors, including max, mean, min, RMS, and var, for two experiments:  monoPcp220.xls (mono-sloped roof -- single roof panel without the rest of the building) and 5A240.xls (sawtooth roof -- building with the sensors on one of the roof panels).
    • Drawings of the buildings used in the two experiments:  monosloped bldg.jpg, sawtooth bldg.jpg, both bldgs.jpg, BuildingSurface1.jpg
    • Autocad drawings of the building and sensor locations:  BuildingSurface1.dxf and FL-30Model Tap Locations.dxf 
  • For this milestone, you must load all the information from files, but you are free to modify the file format(s) to make the job easier for you.  This applies to the building dimensions, sensor coordinates, and the pressure data.
  • In addition, one of the goals of this milestone is to investigate the .dxf file format to decide whether it is feasible in the future to read the building dimensions from such a file.
  • Use CVS to check in your code, SPMP, and a document describing your file format(s).
• Milestone#4 (due Friday, 3/3, by 1:15pm):
  • Modify your Seebreeze application as follows:
    • Display the pressure data as a texture-mapped image on the surface containing the sensors.  Make sure that the image covers the entire surface (even outside the convex hull of the sensors).  One suggestion for performing this display is to create an image that is big enough for reasonable resolution, set individual pixels in the image using the raw sensor data, use bilinear interpolation to fill in the remaining pixels, then splat the image onto the surface.
    • Allow the user the option of manual or automatic scaling of the data.  For manual scaling the user should be able to select the minimum and maximum values displayed, while automatic scaling should compute the minimum and maximum values of the data being displayed.  In either case, intermediate values should be scaled accordingly and values out of range clipped.
    • Display a color bar indicating the range of colors used in displaying the data.  The minimum and maximum values should be written in text next to the ends of the color bar.
    • Indicate the wind direction with a 3D arrow rigidly attached to the coordinate frame of the building.  You will have to augment your data file with the direction, which you should feel free to choose arbitrarily.
    • Allow the user to easily rotate about all three axes.
  • Here is a file showing the wind direction coordinate system for the sawtooth building:  client/sawtooth_wind_direction.gif .  The wind direction is zero degrees pointing straight down, with increasing angles in the clockwise direction.
  • Use CVS to check in your code, SPMP, and a document describing your file format(s).  Include directions in your SPMP on how to compile and run your code if it is not obvious.
• Milestone#5 (due Monday, 4/3, by 2:25pm):
  • Modify your Seebreeze application as follows:
    • Allow the application to handle any building that can be constructed as a set of planar polygon surfaces at arbitrary orientations.  Come up with your own file format, and make it as easy and intuitive to edit as possible.  Specifically, for the simple case of a piecewise-planar function with polygonal regions, the user should be able to specify the building from the plan view, i.e., by (x,y,z) coordinates of the vertices of the polygons.  The format should allow sensor data on any number of the surfaces.
    • Allow the user to choose between multiple wind directions.  You may use a slider (CSliderCtrl, whose callbacks are handled by its parent's OnHScroll method by default; see CWnd::OnHScroll for example code) or buttons or any other method you choose that is intuitive to the user.  You do NOT need to interpolate between angles; rather just show the raw data as given.
    • Use a color scheme that takes advantage of the full range of colors to clearly indicate the values to the user.  Our clients are currently using Matlab's hot color map, shown graphically here (for the actual values, type cc = colormap('hot') in Matlab). Other Matlab color schemes can be found by typing help graph3d in Matlab.  Another option would be to linearly scale from red to white to blue, etc.
    • Add menu bar to window containing OpenGL display to give the user easy ability to load a new file at any time.
  • Make sure code compiles and runs in both Debug and Release modes on as many computers as possible.
  • Test your code on data given by the client:
    • Plan views of three buildings in Florida (FIU1, FIU2, and FIU3) are given in this paper. 
    • Photographs of the 3D scaled models of the buildings:  FIU1 picture, FIU2 picture, FIU3 picture
    • Plan views of the models showing x-y dimensions and sensor locations:  FIU1_plan, FIU2_plan, FIU3_plan
    • Autocad drawings of the models:  FIU1 drawing, FIU2 drawing, FIU3 drawing
    • Some example contour maps of the data collected in the wind tunnel:  FIU1 at 0 degrees, FIU1 at 90 degrees, FIU2 at 0 degrees, FIU2 at 90 degrees, FIU3 at 0 degrees, FIU3 at 90 degrees,
    • Data for multiple wind directions for the single slanted roof is Mono-Cp-multiple-wind-directions.xls .
    • Data for three models:  FIU1OpenCase1, FIU2OpenCase4, FIU3OpenCase4
    • Wind directions with respect to models:  From the contour maps above, noticing the locations of extremely low pressure, it is evident that 0 degrees points upward for FIU1, to the right for FIU2, and downward for FIU3.  In all case the angles proceed in a clockwise fashion.
    • Heights of buildings:  coming
    • x-y sensor locations:  FIU1 sensor coordinates, FIU2 sensor coordinates, FIU3 sensor coordinates
  • Use CVS to check in your code, SPMP, and a document describing your file format(s).  Include directions in your SPMP on how to compile and run your code if it is not obvious.
• Milestone#6 (due Friday, 4/14, by 2:25pm):
  • Your application should have all the functionality of the previous milestone, plus
    • Faster response time.  The user should be able to navigate between wind directions instantaneously.  This can be accomplished by precomputation, a lazy-evaluation cache, or a faster algorithm.
    • Testing.  There should be some test code that verifies that the bitmaps generated are, to some extent at least, correct.  As before, the interpolation algorithm may be simple (e.g., nearest neighbor).  Nevertheless, some sort of quantitative evaluation of accuracy of at least one bitmap is expected.
  • The bitmaps displayed on the buildings should look similar to those generated by Matlab (above).  The user should be able to visually correspond the two, even if the interpolation algorithms are not identical.
  • Here is another sample output that gives an idea of the type of display needed by the client in the future.
• Milestone#7 (due Friday, 4/28, by 2:25pm):
  • Augment your Seebreeze application in the following ways:
    • Better interpolation scheme.  Nearest neighbor or homebrew interpolation algorithms are acceptable, but the results should look qualitatively like the results that our client is currently achieving with Matlab functions.  The interpolation algorithm should be encapsulated into a clean interface in the code (e.g., a single function), so that future developers can easily improve the algorithm without having to interface with the rest of the code base.
    • Home button changes the viewing direction instantaneously to show the canonical top-down view for the building
    • Allow user to select the number of levels for quantizing the display of the pressure values.  When the colors are thus quantized, the user should also be allowed to display black contour lines overlaid on the images.
    • The approximate pressure value under the mouse is displayed, preferably automatically during onmousemove. 

Additional ideas for improving Seebreeze in future milestones:

• Multiple viewports.
• Allow the user the choice between wireframe and solid walls (and between different textures for the walls).
• Implement accurate interpolation between data points.  See Matlab's griddata command (in Matlab, type help griddata for an explanation of the command, and type open griddata to see the code).  Three of the techniques require Delaunay triangulation, while the last one ('v4') does not.  All of them appear reasonable to implement.  For Delaunay code, see one of the following:  Qhull, Bourke's triangulate.c, Shewchuck's triangle code, or Priester's experimental triangulate code .  Some interpolation code is Sakov's natural neighbors .

Instructor: Stan Birchfield, 207-A Riggs Hall, 656-5912, email: stb at clemson
Grader: Devang Bagaria, dbagari at clemson
Lectures: 2:30 - 3:20 MWF, 227 Riggs Hall