About PSP++

PSP++ is a tool to help you estimate the time and amount of code required to write a piece of software. It uses the PROBE method described in Watts S. Humphrey's A Discipline for Software Engineering. The basis of this method is that if your predictions are wrong, they are probably wrong somewhat consistently. That is, you probably either consistently over- or underestimate the size of your projects.

Given a history of your predictions and the corresponding actual results, PSP++ will take your latest prediction and make a prediction of its own, using that history to inform it.

Download the PSP++ installation archive into the directory where you intend to put the folders containing the project list file and your project files.

About PSP++

Rules for recording PSP data

Running PSP++

You will probably want to run PSP++ once after making your initial plan (in order to see its predictions) and once after the project is complete. In either case, follow these steps:
  1. Open the main.lisp file in your ACL2 development environment..
  2. Execute the following two commands
    (main "input/" "output/" state)
    The specified "input/" and "output/" strings specify input and output directories. They are named "input/" and "output/" in the installation examples provided with the PSP++ installation archive.
  3. If all goes well, it will print something like
    ("Generated report for PSP Revision" STATE)
    and a new report will exist in the output directory.

Project List File

PSP reads all its inputs from a single directory. That directory must contain a file named projects.txt, which will tell it what your projects (historical and current) are called. These projects are simply listed one per line, with the most recent last. For each project listed, there should exist a corresponding text file in the input directory. For example, if your projects.txt contains

trig
stat
graph
your input directory should contain (alongside projects.txt) trig.txt, stat.txt, and graph.txt. A report will be generated for the graph project, using the trig and stat projects as history.

Project File

The project file contains the following: These elements can appear in any order in the file. Examples of entire files are available in the input/ directory that comes with the PSP++ installation archive. PSP++ can run without predicted code object estimate, logs, or actual lines of code in a project information file, but it cannot do much without, at least, the time and defect logs and the actual lines of code.

Project Information

To give some basic information about the project in the report, PSP++ asks for your name, the program's name, your instructor's name, and the date. These can be left out if you so choose. This section takes the following form:

name: Your Name
date: November 11, 2009
program: Exercise 1
instructor: Dr. Instructor

Predicted Code Objects

There are two types of predicted objects: new and reused. In a new object, you simply estimated how many lines it will take. For a reused object, you estimate lines of base, added, modified, and removed code. "Base" lines refers to how large the object is when you start with it. "Added," "modified," and "removed" lines refer to how much you add to, modify of, or remove from that base. For any object, you can also name it, classify it into a type, and write a comment. (There are no restrictions on any of these fields.)

An example section follows. Note that lines starting with # are comments.

new objects:

    #### file-bundle module ####

	- name: read-bundle
	  estimated lines: 25
	  type: IO

	- name: write-bundle
	  estimated lines: 25
	  type: IO

	- name: get-from-bundle
	  estimated lines: 6
	  type: Calculation
	  
reused objects:
	- name: split-on-whitespace
	  type: Parse
	  estimated base: 22

Time Log

Next comes the time log. The times in this section are used to inform PSP++'s later time predictions. Each work period is tagged with a phase, which can be named as you choose. For example, you might choose to tag work sessions as "plan", "code", or "test". This choice will be reflected as categories in the report generated. Comments should specifically describe activities and insights of the work period. An example time log follows. Vague comments are unacceptable.

Note: The PSP++ software limits the comment field to one line. One way to deal with this limitation is to use an editor that renders the display in line-wrap mode without inserting end-of-line separators. No matter how you deal with the one-line comment field, descriptive comments, with specifics, are required for each time-log entry.

time log:

	- date: Nov 19, 2009
	  start time: 3:00PM
	  end time: 4:15PM
	  phase: plan
	  comment: Group meeting during class time. Planned out input format, modular breakdown.

	- date: Nov 19, 2009
	  start time: 5:30PM
	  end time: 5:49PM
	  phase: plan
	  comment: Planned output document. [THIS COMMENT IS TOO VAGUE]
	
	- date: Nov 21, 2009
	  start time: 6:07PM
	  end time: 7:43PM
	  phase: code
	  comment: Implemented string distance algorithm. [COMMENTS SHOULD BE DESCRIPTIVE, WHICH MAKES TOO LONG FOR ONE LINE, BUT THE PSP++ SOFTWARE ONLY ALLOW ONE LINE. IT HELPS A LITTLE TO USE AN EDITOR IN LINE-WRAP MODE. REGARDLESS, IT IS IMPORTANT TO MAKE COMMENTS SPECIFIC AND DESCRIPTIVE.]  Discovered that string distances are always natural numbers. Experimented with a tail recursive implementation, but found that structural induction led to a clearly correct solution with less than 5% loss in time of computation and an average 20% increase in space required by computation.

Defect Log

In the defect log, you list and categorize any defects you added to (and fixed in) the software. Like with the time log, these can be categorized by whatever system you choose. Defect descriptions should be specific and usually should lead to a new test in the test suite.

Note: The PSP++ software limits the comment field to one line. It helps a little to use an editor in line-wrap mode. No matter how you deal with this limitation, descriptive comments, with specifics, are required for each defect.

defect log:
	 - date: Nov 19, 2009
	  type: Contract
	  fix time: 3
	  comment: Found that negative input to distance function triggered system crash. Added test specifying negative input  and correct response. [AGAIN, COMMENTS ARE LIMITED TO ONE LINE BY THE PSP++ SOFTWARE, BUT MUST BE SPECIFIC AND WITH REASONABLE DETAIL, WHICH MAKES THEM TOO LONG FOR ONE LINE. IT HELPS TO USE AN EDITOR IN LINE-WRAP MODE.]
          - date: Nov 19, 2009
	  type: API
	  fix time: 2
	  comment: logic error [THIS DESCRIPTION IS TOO VAGUE]
          - date: Nov 19, 2009
	  type: API
	  fix time: 2
	  comment: Confused char-code with code-char

Actual Lines of Code

Once your project is done, you can record how many lines of code it actually took in this section. This will inform PSP++'s judgement of your line-of-code prediction accuracy. Again, here is an example:
actual added lines: 825
actual base lines: 87
actual modified lines: 56
actual removed lines: 12