The following instructions assume that you have already written a program and are now ready to hand it in for corrections — so you can fix it, of course.
In the sections below, you'll want to always perform the bits in green but can typically skip the bits in yellow unless they apply to your situation. (Of course, there are circumstances where your situation may not warrant the green bits, but you'll just have to use your common sense for that!)
For a program, you'll need to create a typescript. It is most helpful if you include your information file, your code, several tests (at least 3-5 but as many as you feel you need), and the answers to any thought-provoking questions for the assignment. (If your code does not yet compile, script the compilation so I can see the errors/warnings you are getting...and just skip the testing bit...)
First of all, start a terminal window (xterm or rxvt in Xwindows at home or simply the console window/standard CygWin prompt). If you are doing this at home, make sure you have a clean dollar prompt before proceeding. Your normal prompt probably looks something like this:
[lots of garbledygook from linux/cygwin]
.!.!.!.!.
......$
To clean it up, you should be able to do this:
[lots of garbledygook from linux/cygwin]
.!.!.!.!.
......$ my_PS=$PS1
[lots of garbledygook from linux/cygwin]
.!.!.!.!.
......$ PS1='$ '
$
Next, we must begin logging all terminal activity. This is done with the *nix utility script. (CygWin users must install the script utility as described here!)
At your $ prompt, enter the script command:
$ script
Script started, file is typescript.
$
The response is that it has begun logging terminal activity into the file typescript (this name can be changed, see the script man page for more about this). Anything that is printed in the terminal or typed into the terminal (until we stop it) will be stored in that file. This lets me see exactly what you did to get certain messages/problems — much easier than you trying to remember what you did the next day ...or even a few minutes later!
Inside your script, I'd appreciate you follow a set of prescribed steps so that I can more easily make corrections for everyone. The first step is to run the pwd utility:
$ pwd
/home/students/..../
$
This tells me what directory (i.e. folder) you were working in when you did this work. (It can also help me identify you if you forget to put in your information file as described next.) If you are working on a company machine and don't want me to see the proprietary directory structure, you may skip this step, but make sure you have your info file!
The next step is for those working at home, mainly, but it wouldn't hurt you to do it here in the lab. Run the CPP (C++ compiling) script and ask it for version information:
$ CPP --version
This is CPP version 1.011. Compiling with:
g++ (GCC) 3.2
Copyright (C) 2002 Free Software Foundation, Inc.
This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
$
That's what I just got on the HP/UX system here on campus. Your response may vary slightly. As long as your numbers are at least that large (1.011 for CPP and 3.2 for g++), you'll be fine.
Our next step is to display the information file. (See the instructions elsewhere about preparing an information file for a program.) This is done with the *nix cat utility:
$ cat triangle.info
/**************************************************************************
* *
* NAME: Jason James CLASS: CSC121-00x *
* *
* Lab: triangles Level: 1 *
* Option: single input set Level: + 1 *
* Total Level: 2 *
* *
* Date Started: initial_date *
* *
* Modification | Date | What was done... *
* --------------+-----------+----------------------------------------- *
* bug fix | the_date | changed erroneous = to + in perimeter *
* | | calculation formula *
* style fix | the_date | added extra \n after 'welcome' message *
* style fix | the_date | made calculation comments reflect new *
* | | option (had left them discussing 'base' *
* | | and 'height' formula...oops) *
* bug fix | the_date | changed erroneous 3 divisor to 2 in *
* | | semi-perimeter calculation *
* style fix | the_date | inserted spaces after prompts for sides *
* | | (they'd gotten lost when prompts were *
* | | re-written for genericity after 'base' *
* | | removal) *
* *
* Description: *
* *
* This program will perform minor geometric calculations for the user *
* given appropriate input data. In particular, we can solve for the *
* area and perimeter of a triangle. Given: *
* *
* ^ *
* /|\ *
* s1 / | \ s2 *
* / | \ *
* / h| \ *
* /____|____\ *
* b *
* *
* We could calculate by: *
* *
* perimeter = side1 + side2 + base *
* *
* 1 *
* area = --- * base * height *
* 2 *
* *
* But to avoid having to have the user enter excess information (like *
* the height here), we can use an alternative formula for the area *
* known as Heron's formula: *
* *
* 1 1 *
* s = --- * (side1 + side2 + side3) = --- * perimeter *
* 2 2 *
* *
* _____________________________________________ *
* area = \/ s * (s - side1) * (s - side2) * (s - side3) *
* *
* While more complex, this formula allows the calculation based soley *
* on the lengths of the three sides -- no height information required! *
* Also note that we no longer need to know what side is the base and *
* will simplify our user interface design! *
* *
* (The terribly-named intermediate variable 's' is sometimes known as *
* the semi-perimeter, but is traditionally simply left as 's' rather *
* than being properly named.) *
* *
**************************************************************************/
$
Your info file will differ somewhat, of course. You must have your name, fill in the 00x with your section (change 121 to 122 or 216 if necessary), list the correct assignment title, options, levels, and totals, and actually describe the program you wrote.
You need not have diagrams. However, if there are applicable formulas, they should NOT be represented with C++ code! (But they don't have to be really pretty, either.)
The modification history/start date are a good thing to have in a team programming environment or in industry, but are not really needed here. Note, however, that we do not log in syntax errors — just logical/style errors. Also, in an industry/team setting, there would need to be an extra column for the programmer's name/initials to identify the 'culprit'. *grin*
And, of course, use your info file's name instead of triangle.info.
After the info file is displayed, please show me your code. Again, we'll use the cat command (for more on this command, feel free to see its man page):
$ cat triangle.C
#include <iostream>
...
$
Here the ... indicates the rest of the program text has been snipped. Yours will be complete. And, of course, yours will probably not be called triangle.C. *smile*
Now that I've seen the code, show me what happens when it compiles:
$ CPP triangle
triangle.C***
$
Luckily, this program had no errors. *grin* Even if your program is still producing errors or warnings, you can hand it in for corrections! (If they are errors, skip the testing phase that comes next...)
With a compiling program (warnings or less), you can show me some representative tests. (When you are debugging the code yourself, you can run as many tests as you like — this should be quite a lot, btw. But when you hand it in to me, pick a handful of tests that are a 'fair' sampling of all of your test cases.)
$ ./triangle.out
Welcome...
...
$ ./triangle.out
Welcome...
...
$ ./triangle.out
Welcome...
...
$ ./triangle.out
Welcome...
...
$
Again, the ... parts represent clipped parts of the execution. Here I've done four test runs. You should choose at least 3-5 tests to show me how you've been testing. Make sure to include any tests that are giving you problems so I can help you find the trouble.
Finally (but certainly not least!), display your answers to the thought-provoking questions (if any; most projects don't have them):
$ cat triangle.quest
1. What...
...
$
You can either re-type the question (or copy/paste it) or simply give me enough context in your answer that I know what the question was about. As these questions are meant to be thought provoking, a simple yes, no, or 12 will not do! You must explain why that is your answer or how something works or what you expect as a result of something. Terse answers don't show me you understand what the question was meant to prompt you to investigate/explore. They will not get you credit.
Once I've seen your question answers, we are done with the script. To tell the system this, either type out exit at the next $ prompt or hit Ctrl-D (hold the control key while striking the d key). You should see:
$ exit
Script done, file is typescript.
$
It even reminds you of the name of the logging file, how nice!
Next, please turn the typescript into a PDF for submitting, download it, and attach it to an email to me.
To give me programs for corrections, a PDF emailed to me (as stated above) is best/easiest for all concerned.
If you simply need a few lines of code looked over quickly between labs or on a weekend, you can also email them to me in PLAIN TEXT. But this will not be acceptable for a final portfolio (or even extra credit) submission. (Those must be in PDF form.)