Due: Wednesday 22 November 2006, 2:00pm
In this assignment, you will perform the first steps in building a graphical polygon editor. These steps include creating a Subversion repository, specifying and testing a Polygon class, and creating a Makefile for the project. You must do this assignment in pairs.
Once your partner has been chosen, both of you will receive an e-mail containing a project directory and a group name. One of you should begin this assignment by downloading hw6.tgz to your project directory and unpacking it with tar -xvzf hw6.tgz. This contains all the files you need to do this assignment.
Make a Subversion repository in your project directory called "svn-repository". Make sure that the group associated with this repository is your project group. Also make sure that you and your group have read, write, execute, and "setgid" permissions on this repository and all its files and subdirectories, but that other users have no permissions. You can do that by executing the following command in the directory where you created your repository (where "c303-?" is your group name).
chgrp -R c303-? svn-repository
chmod -R 2770 svn-repository
Once you have created your repository, import a new project called "polyedit" which contains all the files you unpacked at the beginning of the assignment. You should include no other files in your initial import. Finally, each of you should check out a working copy of this project to your own home directory. You should work in this directory for the remainder of HW6 and HW7.
The purpose of this exercise is to force you to use version control. It will be annoying at first, but it will get easier as you go. To make sure that you are using Subversion, we will check the following things.
Imagine that you had a third teammate, named Hal, who implemented a Polygon class and some related functions and then dropped the class to take a job at the online broker avariceworld.com. You will find his implementation in Polygon.h and Polygon.cpp. Hal wrote some specifications in Point.h, but he did not write specificatoins for any of the methods in the Polygon class. Since you need to use this class, you will write specifications for each method.
Your specifications should use the following format, also shown in lecture:
/**
* Brief one line description of the function.
* Detailed description of the function including...
* Preconditions: What assumptions does the function
* make about its parameters. One example of
* assumption is: "a cannot be null".
* @param a description of the first parameter.
* @param b description of the second parameter.
* @return description of the value that is returned.
*/
int ExampleMethod(int* a, int b);
Put your specifications in Polygon.h Your specifications should explain all the behavior of each method or else include preconditions that explain assumptions you will make about the input. Be careful about what you say, because this specification is like a "contract" for programmers who use your class. It will also influence how you test this class in the next problem.
Note that the Polygon class makes use of the Point class which you implemented in HW5. You should use your own (or your partner's) implementation of this class. If you do not trust your own implementation, you may use the implementation that you find in the solutions to HW5, which will be posted on Friday after class.
The sample solution adds 20 lines of comments to Polygon.h to write specifications for the four methods of Polygon. Your solution should shoot for a similar complexity. Note that you do not need to write specifications for methods that are automatically created by C++ (though doing so is a good idea in practice).
Write a set of black box tests for your Polygon class. These tests must exercise all of the methods in Polygon.h and make periodic checks that these methods are doing what you expect. (You do not need to test the operator>> and operator<< functions defined alongside the Polygon class.) You should name and/or number each test that you make and give a very brief rationale for each test in the readme.txt that you turn in with this assignment.
Note that this is not white box testing! Your tests should use an apporpriate range of inputs given the specification for each method. You should not base your tests on the implementation of these methods. Also note that your tests should observe all preconditions defined in your specifications.
You may put your tests anywhere you wish. The sample solution puts the tests in a static method of the Polygon class called PolyTest. The sample PolyTest contains a total of 79 lines of code, including 25 lines that contain nothing but spaces or comments. This solution defines eight tests, some which check a single function, and some which check several functions at once. Many lines in PolyTest are for printing messages about whether or not a test succeeds. You will see in the next section why this is important.
To finish this assignment, you must create a Makefile that runs your tests. The Makefile must be structured so that typing "make test" in your project directory will build your tests and run them. When your tests run, they should print messages to the terminal that clearly indicate whether they are passing or failing. We will check to make sure that all your tests pass.
Apart from the instructions given above, you may implement this test harness in any way that you wish. The sample solution's test harness adds a file called Test.cpp with a main function that simply calls the test routine PolyTest. The sample solution's Makefile then calls a script called runtest.sh that runs the program and makes a few other checks that cannot be done easily in PolyTest. Depending on how you write your specifications and whether or not you do the extra credit, you may not find it necessary to write such a script.
Remember the course policy on extra credit. You are not expected to do this problem, and you should expect it to be worth very little compared to the rest of the problems in this assignment.
You may have noticed that Polygon.h and Polygon.cpp contain specifications and implementations for operator>> and operator<< that work on Polygons. Test these functions along with the others in your assignment. Hint: have your Test routine send messages to Standard Error instead of Standard Output. You can then read in and write out polygon files in your test program. If you create a script to run tests (like runtest.sh mentioned above) you can add a section that uses diff to compare any output to expected output.
Your solutions should be
Use the standard turn-in instructions described here. You should turn in all files required to build and run your tests, plus the readme.txt file that gives the rationale for each tests. You should also make sure that the files you turn in are identical to the contents of your Subversion repository at the time you turn in. In other words, it should be possible to check out polyedit from your repository and get exactly the same files you turn in.