Contents:  Overview -- Schedule of deliverables -- Suggested project topics -- Computer laboratories -- Project documents -- Suggested C++ coding conventions -- CVS instructions

Overview

A significant part of this class is the semester-long project.  Each group will operate as a small software team, designing, implementing, and documenting a software system of their choice.  Teams will consist of 4-5 members and are expected to build working systems, with features added in successive milestones.  In the first phase of the semester students will form teams, select a problem to solve, and plan and document their project.  In the second phase the teams will implement their solutions by coding.  This two-fold division should not be taken too strictly:  Design and documentation will continue to some extent throughout the second phase, and some exploratory coding should be conducted in the first phase.

Projects should be implemented primarily in C++, have a significant UI interface, and link with at least one external library.  C++ is the most popular and most powerful development language in use today, builds on the widely prevalent C language, and is essential to a well-rounded computer engineering curriculum.  (Portions of the project may be implemented in other languages, though, depending upon the needs of the project.)  UI interfaces present a dimension of design problems, such as event-driven processing, communicating effectively with a user, and possibly multi-threading, that are not necessarily present in other systems.  External libraries enable teams to build upon the work of others and to learn how to use such work effectively.  Deviations from these requirements (such as using Java instead of C++) require prior approval from the instructor and will be allowed only if a compelling argument can be made.

Schedule of deliverables

Documents (problem statement, RAD, SPMP, SDD, and final report) are due by 11:59pm on the date shown.  Documents should be posted on your web page and emailed to the instructor, and a hardcopy turned in by the next morning.  Teams are expected to conduct weekly meetings throughout the semester, submitting the minutes to the instructor via email with the subject line, "Meeting minutes".  Milestones are in-class presentations in which teams communicate their progress to the class via working demos, diagrams, etc; they also include submission of source code.  Each team will meet with the instructor midway through the project for a design review and a code review.  In the final week, teams must present a working demo of their integrated system to the class.  There will be no final exam.

Suggested project topics

Some suggested projects (but feel free to think of your own):

• Bibtex manager.   Latex is a document formatting program widely popular among scientists and engineers because of its excellent handling of complicated equations, along with its structured format and powerful bibliography tools.  Bibtex is the accompanying program for processing a bibliography database, which is a text file (or set of text files) with keywords for author, title, year, etc.  This program would enable a user effectively to manage such a database, allowing operations such as entering a new reference, searching for references related to a specific topic or written by a particular author, converting the format of a reference, etc.  This program contains many interesting UI design decisions, but relatively easy to implement technically.  Some existing solutions include tkbibtex, bibtexmng
• Interactive feature tracker.  This program would enable a user to locate feature points throughout an image sequence interactively, using the KLT feature tracker library as the primary computational engine. 
• Drawing program.  A simple 2D drawing program, similar to xfig.  Even limited 3D support would make the project very interesting.
• Extend an existing open-source project.  Open-source projects are always looking for programmers to help add new features and components.  This project would involve extending an existing project in a well-defined, self-contained manner.  Some examples include
  • GNOME -- GNU desktop environment
  • Octave -- open source numerical software
  • ArgoUML -- open source UML tool
  See also SourceForge.net, GNU help wanted task list, FSF free software directory, Savannah (GNU development)
• Game.  Implement/extend a computer game of your choice.  Ideas can be found among Brown's CS32 projects.

Computer laboratories

• CES Unix labs are in Lowry 125 and Lowry 11, with g++.  If you need an account, send email to unix-admins AT ces.clemson.edu
• Linux machines are on 3rd floor of Riggs in the ullab, with g++.  All students in the class should have accounts on these machines.
• CpSc has some Unix machines in Rhodes for those in computer science
• Windows machines are in Martin and the library, with Visual Studio

Project documents

These documents are required as part of your project:

• Problem Statement.  (pp. 94,154,591)  The problem statement is a high-level overview of the problem and the requirements of the system to solve the problem.  It is developed by the project manager and the client who learn information about each other's expectations and constraints while negotiating a mutually agreeable solution.  It leads to the more detailed documents:  SPMP, RAD, and Project Agreement.  Template -- Example
• Software Project Management Plan (SPMP).  (p. 588)  The SPMP describes all the managerial aspects of the project, including the work breakdown structure, schedule, client requirements, project goals and organization, work packages, budget, and allocation of resources and responsibilities.  It is created before the project kick-off and updated throughout the project as tasks are completed and procedures are refined.  It is written for management and developers.  Template
• System Design Document (SDD).  (p. 283)  The SDD provides a precise description of the software architecture and is used to define interfaces between teams of developers.  It is written for management, system architects, and developers.  Template
• Final report.  The final report serves several purposes.  It serves as a rough-draft user's manual to future users, it documents the system architecture for future developers, it summarizes the accomplishments of the team, and it provides the team with an opportunity to glean lessons from the experience that can be applied to future projects.  The previous documents form a basis for much of the final report.  Template

Other documents include

• Object Design Document (ODD).  Describes the software implementation in detail, including design trade-offs made by developers, guidelines they followed, subsystem decomposition, and class interfaces.  Usually embedded in the source code comments and generated automatically (using Javadoc, Doxygen, etc.) to ensure that it's always up to date.  See p. 376 for a template.
• Requirements Analysis Document (RAD).  (pp. 152,199-200)  The RAD completely describes the system in terms of functional and nonfunctional requirements and serves as a contractual basis between the client and developers.  It is written for the client, users, project management, and some developers (system analysts and system designers).
• Test Plan (TP).  Documents the managerial aspects of testing, such as the scope, approach, resources, and schedule, as well as the requirements and components to be tested.  See p. 476 for a template.
• Test Case Specifications (TCS).  Describes the specific tests to run.  See p. 477 for a template.
• Software Configuration Management Plan (SCMP).  Documents all the information relevant to the activities for monitoring and controlling changes to the system or its models.  See p. 561 for a template.
• Project Agreement.  Formal agreement between client and management, defining the scope, duration, cost, and deliverables of a project.  Subsumes the Problem Statement.  See p. 586.
• top-level design.  Describes the initial decomposition of the system into subsystems.  Leads to SDD.  See p. 590.
• ...

Suggested C++ 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.  Although there is no single agreed-upon standard, here are some conventions that are not uncommon in the industry.

• Spelling and syntax:
  • class, struct, namespace, function:  InterCaps style (first letter of each word capitalized)
  • typedef:  same as class but with Type appended
  • local variables, function parameters: interCaps style (first letter of each word capitalized), except first letter is always lowercase
  • member variables of a class:  same as local variables, but with 'm_' prefix
  • const member variables, enums:  ALL_UPPERCASE_WITH_UNDERSCORES_BETWEEN_WORDS
  • global variables (avoid these of course):  same as local variables, but with 'g_' prefix
  • filename (one file per class):  ClassName.[h,cpp]
  • braces { }:  either in the same column (C++-style) or opening brace at end of line (Kernigan&Ritchie C-style)
  • number of spaces in a tab:  2, 3, or 4
• 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
  • 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

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

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.  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:

First, encrypt your password using
    /usr/local/bin/perl -e 'print crypt("MyPassword","St") . "\n";
then copy and paste the result and send it to the T.A. so we can put it into the CVS passwd file.  Replace MyPassword with your password, and use /usr/bin/perl instead if the above doesn't work.  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. 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
      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, one of either {3dmm, bibtex-manager, gim, klt-ui, or virtual-advisor}
   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 use the command-line version,

1. Download and install cvs on your development machine
2. Create ~/.cvsrc file with a single line: 
   cvs -d :pserver:yourid@cvs.ced.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 one of {3dmm, bibtex-manager, gim, klt-ui, or virtual-advisor}
6. Now CVS is ready!  For reference, see one of the manuals above