REVIC SOFTWARE COST ESTIMATING MODEL USER'S MANUAL VERSION 8.7 August 1989 Developed By Raymond L. Kile TABLE OF CONTENTS SECTION 1 - DESCRIPTION REVIC EQUATIONS SOFTWARE DEVELOPMENT MODES DEVELOPMENT PHASE DESCRIPTIONS MAINTENANCE PHASE DESCRIPTION DIFFERENCES BETWEEN REVIC AND COCOMO CALIBRATION AND ACCURACY OTHER REFERENCE MATERIALS SECTION 2 - REVIC FILES PROGRAM FILES DATA FILES - .RDF DATA FILES - .RFF DATA FILES - .RCF SECTION 3 - GETTING STARTED LOAD SAVED FILE SELECT ENVIRONMENT NEW CODE DESCRIPTION NEW CODE ENTER STATISTICAL TREATMENT OF CODE ESTIMATES DECOMPOSING CODE ESTIMATES PRODUCTIVITY VS SIZE OF CODE PRODUCTIVITY VS ENVIRONMENTAL FACTORS ADA AND PRODUCTIVITY ADAPTED CODE DESCRIPTION ADAPTED CODE ENTER PHASE DISTRIBUTION DISPLAY SECTION 4 - PROGRAM OPTIONS USING THE MENU THE FILES MENU FILES MENU - Save Data File FILES MENU - Load Data File FILES MENU - Restart THE REPORTS MENU REPORTS MENU - Full Report REPORTS MENU - Phase Report REPORTS MENU - Maintenance Report REPORTS MENU - CDRL Page Estimates THE ENVIRONMENT MENU ENVIRONMENT MENU - Edit Factors ENVIRONMENT MENU - Load Factor File ENVIRONMENT MENU - Save Factors ENVIRONMENT MENU - Ada Use THE CONSTRAINTS MENU CONSTRAINTS MENU - Remove Constraints CONSTRAINTS MENU - Total Schedule CONSTRAINTS MENU - Manpower By Phase CONSTRAINTS MENU -Schedule By Phase THE MISC MENU MISC MENU - System Engineering MISC MENU - DT&E MISC MENU - Inflation Factors MISC MENU - Phase Distributions THE DISPLAY MENU DISPLAY MENU - Phase Dist. Display DISPLAY MENU - Risk Display DISPLAY MENU - Activity Display DISPLAY MENU - Maintenance Display DISPLAY MENU - CDRL page estimates THE SLOC MENU SLOC MENU - Both New & Adapted Code SLOC MENU - New Code Only SLOC MENU - Adapted Code Only SLOC MENU - Edit Code Estimate THE BEGIN MENU THE QUIT MENU ADDITIONAL MENU CHOICES CHANGE PROGRAM COEFFICIENTS SAVE PROGRAM COEFFICIENTS SECTION 5 - REVIC EVOLUTION CALIBRATION SUGGESTIONS FOR IMPROVEMENTS SECTION 1 - DESCRIPTION REVIC EQUATIONS The REVIC (Ray's Enhanced Version of Intermediate COCOMO) model predicts the develoment life cycle costs for software development from requirements analysis through completion of the software acceptance testing and the maintenance life cycle for fifteen years. It is similar to the intermediate form of the CONSTRUCTIVE COST MODEL (COCOMO) described by Dr. Barry W. Boehm in his book Software Engineering Economics. The intermediate COCOMO model provides a set of basic equations which calculate the effort (manpower in man-months and hours) and schedule (elapsed time in calendar months) to perform a typical software development project based on an estimate of the lines of code to be developed and a description of the development environment. The forms of the basic equations are shown in Figure 1. B (1) MM = A * ( KDSI ) * Fi D (2) TDEV = C * ( MM ) FIGURE 1 - COCOMO EQUATIONS Equation (1) predicts the manpower (MM) in man-months based on the estimated lines of code to be developed (KDSI is an acronym for Thousand Delivered Source Instructions) and the product of a group of environmental factors Fi. The coefficients (A, B, C, and D) and the factors (Fi) are determined by statistical means from a database of completed projects. The factors attempt to account for the variations in the total development environment (such as programmer's capabilities or experience with the hardware/software) which tend to increase or decrease the total effort and schedule. The results from equation (1) are input to equation (2) to determine the resulting schedule (TDEV is an acronym for Time for Development) in months needed to perform the complete development. The COCOMO model then provides a set of tables which provide a distribution of the effort and schedule to the phases of development (system engineering, preliminary design, critical design, etc.) and activities (system analysis, coding, test planning, etc.) as a percentage of the total. SOFTWARE DEVELOPMENT MODES The intermediate form of the COCOMO model has three basic modes of software development. These modes describe the overall software development in terms of the size, number of interfaces, and complexity. Each mode provides a different set of coefficients for the basic equations. In addition to the three COCOMO modes, REVIC provides a fourth mode specifically for Ada projects. The four modes are described in TABLE 1. ORGANIC - Standalone program with few interfaces, a stable development environment, no new algorithms, and few constraints. Usually very small programs. SEMIDETACHED - A combination of organic and embedded features. EMBEDDED - Programs with considerable interfaces, new algorithms, and/or extremely tight constraints. Usually very large or complicated programs. ADA - Programs designed and developed using the Ada design methodology, language, and APSE. TABLE 1 - COCOMO/REVIC Software Development Modes REVIC assumes a default of Embedded mode upon startup. If you need to change the mode, you will have the opportunity in the SELECT ENVIRONMENT display screen described later in this manual. DEVELOPMENT PHASE DESCRIPTIONS The COCOMO model, as represented by equation (1) and (2), is based on the development phase of typical software development activity. The development phase periods are described in TABLE 2. There are several things to note about Table 2. First, the development period for the COCOMO model does not include the system engineering phase. The amount of effort expended in a system engineering phase can vary dramatically based on how much work was previously done in a Concept Validation phase or during the proposal period. The REVIC program predicts the effort and schedule in the system engineering phase by taking a percentage of the development phases. REVIC provides a default value for this percentage based on average programs, but allows you to change the percentage if desired. Phase Start Milestone End Milestone System Engineering Generally Contract Completion of S/W Award Specification Review (SSR) *Preliminary Design Completion of S/W Completion of Specification Review Preliminary Design (SRR) Review (PDR) *Critical Design Completion of PDR Completion of Critical Design Review (CDR) *Code & Unit Testing Completion of CDR Completion of CSC Testing by the S/W programmers (CUT) *Integration & Test Completion of CUT Completion of the Prelim Qual Test (PQT) at the CSCI level Development Test & Completion of the Completion of the Evaluation Formal Qual. Test System Level (FQT) at the CSCI Functional and Physical Configuration Audits (FCA, PCA) * - Items are covered in the Intermediate COCOMO equations TABLE 2 - Development Phase Descriptions The second item of note in Table 2 is that the COCOMO development phase stops at completion of the integration and test phase (after successful PQT) This phase is characterized by the integration of software CSCs into CSCIs and testing of the CSCIs against the test criteria developed during the program. It does not include the subsystem level integration (commonly called software builds) of CSCIs together or system level testing to ensure the requirements of the system level specifications are met. The S/W to S/W and S/W to H/W integration and testing is accounted for in the Development Test & Evaluation (DT&E) phase. The REVIC program predicts the effort and schedule for this phase similarly to the system engineering phase, by taking a percentage of the development phases. Again, REVIC provides a default percentage for this phase based on average programs and allows the user to change the percentage if desired. Some contractors combine the Code and Unit Test phase with the Integration & Test phase and call the result the Construct phase. The total effort predicted by the REVIC model for the two combined phases should be added together into the Construct phase if you are using that convention. MAINTENANCE PHASE DESCRIPTION The REVIC model provides an estimate for the maintenance of software over a fifteen year period by implementing the equation described in Dr. Boehm's book and shown in Figure 2. (3) MMAM = ( MMnom) * ACT * MFi FIGURE 2 - COCOMO MAINTENANCE EQUATION In equation (3), MMnom is the result of equation (1) without multiplying by the environmental factors (Fi). The first new term in the equation, ACT, is the annual change traffic expressed in percent. The second new term in the equation, MFi, is a set of maintenance environment factors. REVIC provides a default percentage for ACT and also allows you to change it if desired. The program assumes that there will be some transition period after delivery of the software during which residual errors will be found before reaching a steady state condition and provides a declining, positive delta to the ACT during the first three years. In the first year, the ACT is multiplied by 1.5 by REVIC, while in the second year the multiplier is 1.3 and the third year's is 1.15. The fourth and all subsequent years apply the straight value specified for ACT. DIFFERENCES BETWEEN REVIC AND COCOMO The primary difference between REVIC and COCOMO is the basic coefficients used in the equations and REVICs addition of a mode for Ada programs. REVIC has been calibrated to a data base of recently completed DOD projects and uses different coefficients. On the average, the values predicted by the basic effort and schedule equations will be higher in REVIC vs COCOMO. The Air Force's Contract Management Division published a study validating the REVIC equations using a data base (the data base collected by the Rome Air Development Center) different from that used for calibration. In addition, the model has been shown to compare to within 2% of expensive commercial models (see CALIBRATION AND ACCURACY below). Other differences arise in the mechanization of the distribution of effort and schedule to the various phases of the development and the automatic calculation of standard deviations for risk assessment. COCOMO provides a table for distributing the effort and schedule over the development phases based on the size of the code being developed. REVIC provides a single weighted 'average' distribution for effort and schedule, along with the ability to let the user vary the percentages in the system engineering and DT&E phases. The REVIC model has also been enhanced by using PERT statistical methods for determining the lines of code to be developed. Low, high, and most probable estimates for each CPC (computer program component) are used to calculate the effective lines of code and the standard deviation. The effective lines of code and standard deviation are then used in the equations rather than the linear sum of the estimates. In this manner, the estimating uncertainties can be quantified and, to some extent, reduced. A sensitivity analysis showing the plus and minus three sigmas for effort and schedule is automatically calculated using the standard deviation. In the area of public domain software, there have been many faithful attempts to mechanize the COCOMO model in spreadsheets, usually Lotus based. All of these efforts suffer from the serious flaw of requiring the user to be extremely knowledgable about the model and capable in manipulating the spreadsheet. REVIC stands head and shoulder above those attempts in its ability to isolate the user from any required detailed knowledge of the algorithms. Through the use of non-modal programming with extensive prompting and help screens, REVIC removes the typical intimidation factor that prevents analysts from using models sucessfully. The majority of the REVIC program is concerned with a user-friendly method of prompting for the information needed by the program to determine the proper coefficients, factors, and distribution tables. In effect, the program provides a complete interface between the user and the model. REVIC further distances itself from other public domain models in providing the capability to interactively constrain the schedules and staffing levels. Schedules can be constrained either in the aggregate or by phase of the development effort. Staffing can be constrained by phase. Using these features, the analyst can estimate cost over/underuns and schedule slips at any major milestone. Once the initial input process is complete (i.e. the program has enough information to calculate the effort and schedule), the user is presented with a custom menu which allows fully exercising the analytical features and displays of the program. All inputs are easily recalled and changed to facilitate analyses, and in addition, the user can constrain the solution in a variety of ways as described above. CALIBRATION AND ACCURACY The level of accuracy provided by the model is directly proportional to the confidence you have in the line-of-code (LOC) estimates and the description of the development environment. When little is known about the project or environment, the model can be run leaving all the environmental parameters and default values at their nominal settings. The only input required is a LOC estimate. As the details of the project become known, the data file can be reloaded into the program and the nominal values can be changed to reflect the new knowledge. In this way, the accuracy of the model continually improves. REVIC's coefficients have been calibrated to a data base of recently completed projects (development phases only) by using the techniques described in Dr. Boehm's book, and provides estimates which are within 5% of the projects in the data base. The REVIC model was compared to the commercially available System 3 model (Dr. Randal Jensen's model as distributed by Computer Economics Inc.) during a study performed for the Department of Defense. After establishing identical environments for both models, the average efforts predicted by both differed by less than 2%, while the average schedules differed by 6%. The primary reason for the greater schedule variance is probably due to REVIC's (and COCOMO's) level step staffing profile compared to the Jensen model's smooth Rayleigh curve staffing. OTHER REFERENCE MATERIALS While it is not necessary to have understood (or even to have read) Dr. Boehm's book to run the model, it is strongly suggested that you do so to have a fuller understanding of the implications of parametric modeling. In particular, the book gives detailed descriptions of the software development process and the factors that tend to increase/decrease the total effort and schedule. Context sensitive help is available on-line while running the REVIC model to assist you in establishing the proper environmental description. In all cases, the information given is enough to input data and get results, however Dr. Boehm's book gives a more complete explanation with many examples. SECTION 2 - REVIC FILES PROGRAM FILES REVIC is distributed as a single executable program (REVIC.EXE) for IBM and compatible personal computers using the MS-DOS operating system. During the program's execution, a temporary work file is created to store information about the line of code estimates. This file is always called "WORKLOC.CDE" and may be deleted from your directory if found. It will not affect the REVIC program to leave it on your disk. For speed of execution and easier operation, a separate subdirectory should be created for the REVIC program and the data files that will accumulate. Copy the REVIC.EXE file into the subdirectory before starting the program. The following DOS statements give an example of creating a new subdirectory called "REVIC" and then copying the program from its distribution disk (assumed to be in disk drive "A") to the new subdirectory. C:>MD REVIC C:>CD REVIC C:\REVIC>COPY A:REVIC.EXE DATA FILES - .RDF The REVIC program provides the ability to save your estimates during the course of running the program for reuse later. The files are identified by the '.RDF' extension and are created whenever you save the results of an estimating session. RDF (REVIC Data File) files are ascii files containing all the program's inputs, results variables, and program flags. These types of files can be read into the REVIC program and will result in the exact state the program was in when the file was saved. This allows you to revisit previous estimates and change the inputs. RDF files could also be read by user written programs for specific purposes. The REVIC Programmer's Notes gives a description of RDF file contents. DATA FILES - .RFF A second type of file is identified by the '.RFF' extension. RFF (REVIC Factor File) files are ascii files containing the complete set of environmental factors describing the contractor's development environment and certain project factors such as complexity, security, etc. These files allow you to set up default environments that can be read into the REVIC program and save you having to manually specify the environment. For example, you could have a RFF for one contractor or type of project and another RFF for a different contractor or type of project. An analyst would not be required to 'guess' what environment to specify for a given project. He would merely load the appropriate RFF and proceed with the analysis. The program allows you to save the current environment to a RFF file at any time. DATA FILES - .RCF A third type of file is identified by the '.RCF' extension. RCF (REVIC Coefficient File) files are files containing the coefficients for the equations used by the program. These files may be provided to tailor the calibration of the model to specific circumstances. If present, these files may be selected by the user during the execution of the REVIC model. When selected, a message will appear on the displays and reports that non- standard calibration coefficients were used. SECTION 3 - GETTING STARTED To start the program, type its name at the DOS prompt (>) followed by a RETURN (cr) as follows: > REVIC (cr) The program will load and present its opening screen giving the version number of the program and a menu of choices that can be taken. The opening screen suggests that users who are not familiar with the model choose the 'Begin' option from the menu. Experienced users may want to skip the beginning screens to get directly to the ability to load a custom environment or a previously saved data file. They may do so by choosing the appropriate menu item from the opening screen. Choosing the 'Begin' option will result in a fixed series of input screens which will ensure that the user enters all appropriate information. The order of this script is described in the remainder of this section. For information on the other menu choices, see Section 4. LOAD SAVED FILE The program presents you with screens giving instructions and requesting various inputs. After starting the program and choosing the 'Begin' option from the opening screen, you will be presented with the only unique screen in the REVIC program (all other screens can be recalled through appropriate menu choices). This screen is showed only when starting the 'Begin' script. You are asked if you want to load a previously saved data file (RDF). A message at the bottom of the screen tells you that hitting the RETURN key without entering anything will always default to the choice enclosed within square brackets. In this screen, the default choice is [N], or NO. Once you have run the program and have saved one or more data files, you may want to start out by loading one of them. If that were the case, you would hit the 'Y' or 'y' key. The file would be opened, read, and the model would jump to the results display. If you answered 'Y' to this prompt and there were no previously saved RDF files, the program would inform you that no files were found and allow you to continue. The first screen, just described, is unique because it determines the mode of operation of the program. If you do not have a RDF file to load, you must enter certain amounts of data to get an estimate. Answering 'NO' to the first screen's prompt means that the program will put up a predetermined minimum number of screens, in order, to ensure that sufficient data has been input to make a valid estimate. Answering YES and subsequently loading the RDF file, takes you directly to the result screens. Once at the result screens, you take control of the program and tell it what you want to do, and the order to do it in, by selecting from a menu of choices. The remainder of this section will assume that you choose 'NO' to the first screen's prompt. SELECT ENVIRONMENT The next screen presents you with 24 environmental factors and default variables. The screen is divided into two sections. The upper part of the screen displays nineteen environmental factors and the software development mode. Below that is a group of four variables with their default settings. Use the cursor control keys (arrows, PGUP, PGDN, HOME, END, TAB, SHIFT TAB) to move between fields. The current field selected will be highlighted. When an environment factor field (upper part of the display) has been selected, you can increment the setting by hitting the SPACE BAR. The setting displayed and its value will increment to the next higher rating until reaching the maximum and will then start over at the lowest rating in a circular buffer. The total product of all nineteen factors (the software development mode is not one of the factors, but is shown with a value of 1.00 in this display to avoid confusion) is continuously updated and displayed immediately below the factors. The total effort and schedule predicted by the model is directly proportional to this number. Larger values result in more effort and schedule, while smaller values result in less effort and schedule. Note that not all the factors have larger values for high settings versus low settings. It will be a temptation to play with the factors to make the predicted effort and schedule come out to the RIGHT ANSWER. Avoid that temptation. You should always set the factors to the actual environment to the best of your knowledge. If you don't like the resulting answer then something in the actual environment or size of the program needs to be changed, but don't fool yourself by specifying an environment that doesn't correspond to reality. The four variables in the lower part of the screen must be manually input. Each field has a specified length. While entering numbers into a field, if you go over the specified length the field will reset to zero. If you enter a number that fits within the specified length but is outside of a normal range of values for that factor (for example - the number of hours in a man- month can't exceed 248), the program will not replace the default value. This limit checking is not performed until you exit the screen by hitting the ESCAPE key. If you entered an improper number and left the screen, when you reenter this screen at a subsequent time, the value displayed will show that the default number is still in place. For this screen and most subsequent ones, a notice is shown at the bottom of the display describing the function keys that are active. For this screen you have three choices. Selecting F1 will take you to the on-line help file. You will get a specific help screen based on which field was highlighted when you asked for help. The second choice is Selecting the ESCAPE key. This will cause the program to check all fields, limit check the variables, enter the appropriate data into the programs data base, and proceed to the next screen. The final choice is to Select the F9 key. This will result in quitting the REVIC program. All data input will be lost if you choose this action. All of the environmental factors are described in Dr. Boehm's book and in the help file, therefore, they will not be discussed in this manual. Additionally, the four variables are described in adequate detail in the help screens and will also not be discussed. NEW CODE DESCRIPTION Entering the estimates for lines of code to be developed is broken up into two main categories. The first is entirely new code and the next screen describes how the program will ask for the lines of new code to be input. This informational screen is only shown when you have choosen the 'Begin' option from the menu. Arriving at the code enter screens by any other mode assumes that you know what the program will ask for. In essense, power users are not handicapped by having to waste time reading this screen since the same information is available from the help screen available when at the next display. Hit any key after reading the information to proceed. NEW CODE ENTER The program stores four pieces of information for each code module in the temporary WORKLOC.CDE random access file; the module's name, the low estimate (LE) for lines of code, the high estimate (HE) for lines of code, and the most probable (MP) estimate for lines of code. The four items are prompted for in four fields. Use the cursor control keys to move between the fields and enter data. The data you input is not entered into the program until you select the F2 key as described on the screen. Help is available by selecting the F1 key. The only number that is required to be entered is the most probable estimate, the other fields may be left blank. If the low and high estimate fields are left blank when the F2 key is selected, they will both be defaulted to the most probable estimate. If only the high estimate field is left blank, it will be defaulted to the most probable estimate. If only the low estimate field is left blank, it will be defaulted to zero. Once you are through entering new code modules, select the ESCAPE key to exit the screen and proceed immediately to the adapted code screens, or select the F9 key to quit the REVIC program. All of the information entered is printed in the appropriate report, therefore it is usefull to put in descriptive names for the modules if you will be printing a lot of data. STATISTICAL TREATMENT OF CODE ESTIMATES The REVIC program goes beyond the COCOMO model by asking for the low and high estimates for the lines of code to be developed. The program calculates an effective lines of code (EDSI) and the standard deviation (SD) based on the spread between the high and low estimates. Figure 3 shows the equations used. (4) EDSI = (LE + 4MP + HE) / 6 (5) SD = (HE - LE) / 6 FIGURE 3 - STATISTICAL CALCULATIONS The EDSI is converted to KDSI by dividing by 1000 and is the actual number used in equation (1). The standard deviation is used to present a risk analysis display which will be described later in this manual. When the F2 key is selected, the currently displayed data is entered into the program's data base (actually stored in the WORKLOC.CDE file). The fields are then emptied and the module number is incremented in the display. The program is then ready for another code module to be entered. You are limited in the number of code modules that can be entered only by the amount of available space on your disk. DECOMPOSING CODE ESTIMATES Some thought should be given to how the software is decomposed and entered into the program. When more than one module are entered, the EDSI and SD are calculated separately for each module. The EDSIs are added together while the SD of the combined modules is calculated using the square root of the sum of the squares method. This means that the uncertainty in the lines of code as reflected in the standard deviation is smaller when the code is decomposed. In other words, the SD for a single module of 100,000 lines of code with 10% uncertainty will be larger than the sum of ten modules of 10,000 lines of code, each with the same 10% uncertainty. Thus it is more accurate to enter 100,000 lines of code as ten, or more, modules than it would be to enter it as one module. There may be times when you want the SD to be high to see what the bounds of your problem are, but remember that the accuracy of this statistical aproach suffers. PRODUCTIVITY VS SIZE OF CODE The software development productivity, in terms of lines of code developed per man-month expended, is non-linearly, inversely proportional to the total size of the project. In other words, the larger the size of code to be developed, the lower the actual productivity will be. The practical effect of this phenomenon is that if you can divide a 100,000 lines of code development into two independent teams, each with 50,000 lines of code, it will consume less total effort. Currently, you would have to run the model twice with 50,000 lines of code and add the results together (or run it once with 50,000 LOC and multiply the effort results by 2). A future enhancement to REVIC will allow you to enter the two code modules and specify how they should be treated (as independent efforts or added together); but for this version, they will be added together and the results will reflect the lower productivity due to the larger size. PRODUCTIVITY VS ENVIRONMENTAL FACTORS The software development productivity, is also directly related to the resulting modifier when all nineteen environmental factors are multiplied together. A lower MDD or modifier rating will result in a higher productivity rating. Figure 4 shows the relationship between productivity, MDD and size of code for the semidetached mode. Organic and Embedded modes would have similar curves with different values. FIGURE NOT AVAILABLE ON DOWNLOADED VERSIONS OF THE USER'S MANUAL. FIGURE 4 - PRODUCTIVITY RELATIONSHIPS ADA AND PRODUCTIVITY The exponent used for the Ada mode in equation 1 is less that 1.0 (currently .941 is used in version 8.7.4 and greater). This has unique implications for developments using the Ada programming support environment (APSE) and language. In general, everything said above concerning productivity vs size is reversed for the Ada mode. Since the exponent is less than unity, the resulting effort tends to be correspondingly less as the size increases and thus the productivity increases with size. The exponent used in REVIC is close enough to unity that the productivity can be considered essentially constant over the range of code sizes and other factors can be used when deciding how to decompose the software. Productivity will still vary with the environment in exactly the same manner as described for non-Ada modes. The phenomena described by the Ada exponent seems to justify the rationale that enforcing interfaces by using the separably compilable specifications vs body allows Ada developments to overcome some of the manpower normally wasted in communicating between design/programmer teams. ADAPTED CODE DESCRIPTION The next screen reached after selecting the 'ESCape' key in the new code enter screen describes how the program expects data to be input when you are adapting or modifying an existing software module as part of the overall software development. You are asked if you have any adapted code modules to enter. The default choice available by hitting the RETURN key without entering anything is 'NO'. If you take the default action, the program will go on to calculate with all the data currently entered and display the first results screen. Entering 'Y' or 'y' will cause the program to show the adapted code enter screen. (Actually, entering any character except a "Y" or 'y' will default to the 'NO' option.) Again, this screen is only shown when arriving here via the 'Begin' option from the menu. Power users do not have to suffer this screen everytime. ADAPTED CODE ENTER The adapted code enter screen is mechanically similar to the new code enter screen already described. Only the types of data being requested are different. The help screens provide a complete description of the requested data, therefore, the information will not be repeated here. Dr. Boehm's book provides a particularly good discussion of adapted code and is recommended reading. The program calculates the Equivalent Delivered Source Instructions (EDSI) in accordance with the equation shown in FIGURE 4. The Adapted Delivered Source Instructions (ADSI) is multiplied by the percents of design modification (DM), code modification (CM), and retesting (IM) required. As an example, an adapted code package which had exactly 100% design modification, 100% code modification, and 100% retest required would result in the EDSI being equal to the ADSI. For statistical purposes, REVIC assumes a 10% (a total of 20% of the calculated EDSI) standard deviation for the adapted code modules. The means of entering the data into the program's data base and exiting the screen are identical to those described for the new code enter screen. (6) EDSI = ADSI * (.4 DM +.3 CM + .3 IM) / 100 FIGURE 4 - Adapted Code Calculation PHASE DISTRIBUTION DISPLAY The next screen display marks the end of the predetermined path started when you chose the 'Begin' option when starting the REVIC program. The phase distribution display shows the predicted effort, schedule, and required manpower distributed by the development phase (system engineering, preliminary design, etc.). From this point on, you will choose your actions from a menu of choices at the bottom of the screen. Besides changing any of the previously input data, you have the opportunity to perform trade-off analyses by constraining manpower or schedules, or both. The power of REVIC goes beyond merely estimating a program's cost. REVIC can, and should, be used as an on-going tool to evaluate the program's progress. Using the ability to specify schedule or manpower by specific phase of the program allows you to determine such things as the effects of understaffing on cost/schedule, the costs of schedule compression, or the expected overruns due to line of code growth. Changing the environmental factors allows you to quantify the results of staffing with new hires when the program was bid based on experience people or vice-versa. The list of ways in which the REVIC program can be used to analyze programs is limited only by your imagination. SECTION 4 - PROGRAM OPTIONS USING THE MENU Once you have reached the phase distribution display or you choose to use the other choices from the menu at the startup screen, further use of the model is directed by your use of the menu displayed at the bottom of the screen. The top line of the two lines displayed is the main menu. Under it are the sub items which are available from the main menu item which is currently highlighted. You may use the cursor arrows to move between the main menu items and see the full set of subitems available. When you have highlighted the main menu item you wish to select, select the RETURN key. You may also select the main menu item directly by hitting the first letter of the main menu item. After you have selected a main menu item, the main menu line is hidden and the submenu becomes active. Choose an item from the submenu in the same manner, with the cursor keys and RETURN key or by selecting the first letter of your menu choice. If you make a mistake or change your mind at the submenu level when using the cursor keys, you may return to the main menu by selecting the ESCAPE key. Each menu and suboptions are described in the following sections. THE FILES MENU The first item in the main menu is the FILES menu. Under the FILES menu are choices which allow you to save REVIC Data Files (.RDF), load previously saved RDF files, and restart the program. FILES MENU - Save Data File When you choose the Save Data File option, the program will prompt you to enter a filename in which to store the current data. The filename should follow the normal DOS naming conventions. Any letters after eight characters will be ignored. The program will open a data file in the current subdirectory, write the information to it, close the file, and return to the main menu display. If you select the 'RETURN' or 'ENTER' key without entering anything, the program will cancel this action and return to the main menu display. FILES MENU - Load Data File When you choose the Load Data File option, the program will put up a list of all the RDF files that exist within the default or last specified subdirectory. You can then use any of the normal cursor control keys to select a file from the list. Selecting the 'RETURN' or 'ENTER' key will cause the program to open and read the filename that is highlighted as a result of your cursor selection. Selecting the 'ESCape' key will cancel this action and return to the main menu display. If there are no RDF files in the current subdirectory, a message will be displayed and the program will return to the main menu. FILES MENU - Restart The Restart option will reinitialize all variables and return to the startup screen. THE REPORTS MENU The second item in the main menu is the REPORTS menu. You have the choice of getting a full report, an abbreviated phase display only report, a maintenance report, and a CDRL page estimate report. Besides using the REPORTS menu, you can always use the SHIFT- PRT SCRN method of getting a print out of whatever is currently displayed on the screen. Currently REVIC only supports line printers. REPORTS MENU - Full Report The Full Report choice will give you a print out containing the phase distribution display, the activity distribution display, the risk display, the environmental factors with their current settings, and the line of code estimates used in the calculations. You will be prompted for a name to identify the report and be asked to put the printer on-line before proceeding. The printed report will have the current date and time from the system clock for reference. If you have entered a session name in a previous report and do not need to change it, you can hit the RETURN key without entering anything. The previously entered session name will be used. If you choose to enter a new name, it will become the default name for all subsequent displays and reports until you choose to change it again. The REVIC program will respond differently to printer problems depending on what type of computer and version of DOS you are using. It may crash the program if you are not on-line when the program attempts to start printing, so heed the warning message and set up your printer before allowing the program to continue (it is a good idea to save the data to a RDF file first) or cancel the print job. After printing the report, the Phase Distribution Display will be shown on the screen along with the main menu. REPORTS MENU - Phase Report This option prints out only the Phase Distribution Display and the environmental factors. You are prompted for a session name and to make sure the printer is on-line in a similar manner to the Full Report option. After printing the report, the Phase Distribution Display will be shown on the screeen. REPORTS MENU - Maintenance Report This option prints out the fifteen year maintenance projections. You will be prompted for the session name and asked to put the printer on-line. The report will have the current date and time for reference. Maintenance reports show the total effort in manmonths, the average number of full time support personnel required, the average inflated labor rate, and the extended total costs per year for the direct labor. REPORTS MENU - CDRL Page Estimates This option prints out the page estimates for DOD-STD-2167A type documents. The prompts for session name and putting the printer on-line are identical to those described for the other reports. You will be given the approximate page estimates for most of the typical types of documents. The listing does not mean to imply that one of each type document must be produced and is costed in the predicted effort. The program is calibrated to the completed programs in a data base, and therefore represents an average amount of documentation. If your program has an abnormal amount of documentation required, you might want to increase the effort over that predicted by the model to accomodate your special circumstances. THE ENVIRONMENT MENU The third item in the main menu is the ENVIRONMENT menu. You have the choices of editing the environmental factors, loading a previously saved RFF file, saving the current factors to a RFF file, loading a previously saved RCF file, or specifying the Ada factors. ENVIRONMENT MENU - Edit Factors This option will put up the Select Environment screen described in SECTION 3, GETTING STARTED. You may change any of the settings or variables within this screen. After exiting the Select Environment screen, the program will calculate the new results and put up the Phase Distribution Display. ENVIRONMENT MENU - Load Factor File This option will cause the program to search the current default subdirectory for any REVIC Factor Files (RFF). A list of RFF files will be displayed and you will be able to use the cursor control keys to highlight the file you want to load. When you have highlighted the right file, select the ENTER or RETURN key to select it. The program will open the file and read in the data. After closing the file, the program will put up the Select Environment screen to show what was loaded. After exiting the Select Environment screen, the program will recalculate the results and put up the Phase Distribution Display. Any forcing, such as forcing the manpower by phase or the total schedule, will be lost and only the results of the nominal calculations will be displayed. Hitting the ESCape key will cancel the action and return you to the main menu. If there were no files in the current subdirectory, a message will be shown and the model will put up the Select Environment screen with the current settings. ENVIRONMENT MENU - Save Factors This option allows you to save the environmental factors, including the program default variables and inflation rates, to a REVIC Factor File. The program will prompt you to input the filename to use, then will open the filename under the current default directory, write the data to the file, close the file, and then return you to the main menu. If you enter an improper filename, the program will display a message and give you an opportunity to correct it. Selecting ENTER or RETURN without entering anything will cancel this action and return you to the main menu. ENVIRONMENT MENU - Get Coefficient File This option will cause the program to search the current default subdirectory for any REVIC Coefficient Files (RCF). A list of RCF files will be displayed and you will be able to use the cursor control keys to highlight the file you want to load. When you have highlighted the right file, select the ENTER or RETURN key to select it. The program will open the file and read in the data. After closing the file, the program will recalculate the results and put up the Phase Distribution Display. Any forcing, such as forcing the manpower by phase or the total schedule, will be lost and only the results of the nominal calculations will be displayed. Selecting the ESCape key will cancel the action and return you to the main menu. If there were no files in the current subdirectory, a message will be shown and the model will return to the main menu. ENVIRONMENT MENU - Ada Use This option puts up an informational screen which tells the user that Ada has been implemented as another mode in the Edit Factors screen. THE CONSTRAINTS MENU The fourth item in the main menu allows you to force the model to accept a schedule or manpower loading of your choice. When you force the model, it recalculates the effort and schedule according to whatever constraining condition you have input. Note that shortening the schedule will result in a lower setting (with a higher numeric value) for the schedule environmental factor, with a proportional increase in the total effort to develop the software. CONSTRAINTS MENU - Remove Constraints This option will remove all schedule or manpower constraints applied thru the CONSTRAINTS menu. It will recalculate and display the nominal results in the Phase Distribution Display. After chosing this option, or before applying any constraints, the Phase Distribution Display will reflect the schedule is NOMINAL. Any other value for the schedule in the display indicates that the program is still in constraint mode. CONSTRAINTS MENU - Total Schedule This option allows you to force the model to accept a total schedule of your choice. You will be given a message telling you that the model will not allow you to specify a schedule that is shorter than approximately 75% of the nominal schedule it calculated. The program will tell you what that value is and will then prompt you to input your desired total schedule. If you select the ENTER or RETURN key without entering anything, this action will be canceled and you will be returned to the main menu. After inputting your desired schedule, the program will iterate its calculations to arrive at a solution that meets your desired schedule within the iteration criteria of one tenth (.1) of a month and display the results in the Phase Distribution Display. The display will automatically change the value of the schedule actor and display the current setting. If you enter a total schedule that is too short, the program will put up an error message and tell you to reenter. The value shown for the minimum schedule is rounded off for display, therefore you may need to enter a number that is slightly higher if you are trying to get the shortest possible schedule. The minimum possible schedule is maintained properly even when you choose to change the system engineering or DT&E schedule through the MISC menu. The minimum possible schedule is based on the development phase portion of the entire lifecycle. You can shorten the total schedule by zeroing out either of the two non-developmental phases, but you will still not be allowed to shorten the nominal development phase below the minimum. CONSTRAINTS MENU - Manpower By Phase This option allows you to specify the number of full time personnel in each phase of the total lifecycle. The model will put up a display of what is currently in each phase. Use the cursor control keys to move around and change the values as desired. When you tell the program to enter the data by selecting the 'F2' key, the schedule will be calculated. If the resulting schedule is below the 75% minimum schedule, you will be given an error message and allowed to change your inputs. Selecting the ESCAPE key will cancel this action and tell the program to recalculate the nominal values. Note that this option allows you to perform a type of cost to complete analysis. If you are at one of the major milestones, you can force the model by putting in the actual manpower used up to that point. The Phase Distribution Display will show what the effect on the total effort and schedule will be (assuming that the program is staffed according to the nominal levels for the rest of the program). You can also put in any proposed under or over staffing and determine the total effect in a similar manner. CONSTRAINTS MENU -Schedule By Phase This option is similar to the Manpower By Phase item except that you are specifying the actual schedule. The program will check against the 75% minimum schedule and then recalculate the effort and personnel needed. This option allows you to perform a similar analysis to the Manpower By Phase option. In this case, you can force the model by inputting the actual schedule through the major milestones and let the model tell you the total effect on effort and total schedule. THE MISC MENU The next item in the main menu allows you to change the defaults used in calculating the system engineering and DT&E phases, allows you to specify the inflation to be used in calculating the fifteen year maintenance effort, and will allow you to change the phase distribution percentages used in allocating portions of the effort and schedule to the phases of development (system engineering, preliminary design, etc.). MISC MENU - System Engineering This option allows you to change the default percentages used in calculating the effort and schedule for the system engineering phase of the lifecycle. Use the cursor control keys to move between the fields and enter your new values. Selecting the 'F2' key enters the data and tells the program to calculate the results and put up the Phase Distribution Display. Entering a zero in the percentage field will zero out the system engineering phase. Selecting the ESCAPE key will return the system engineering values to the original defaults. The value to be input for the schedule should be the actual months to be used by the model. MISC MENU - DT&E This option is similar to the System Engineering option. In this case you are changing the values for the Development, Test, and Evaluation phase of the lifecycle. Note that the value for the DT&E percentage set in the Select Environment display changes the default value that is used in the calculations. MISC MENU - Inflation Factors This option allows you to specify the inflation factors to be used in the fifteen year maintenance calculations. Use the cursor control keys to move around and change the values. Selecting the 'F3' key will reset all fifteen values to zero. Selecting the 'F4' key will replace all fifteen values with the value that is currently in year 1. Selecting the ESCAPE key will enter the values and return you to the main menu. Note that the inflation factors are saved in the REVIC Factor File. Upon program startup and after a restart, the inflation factors are all set to zero. MISC MENU - Phase Distributions This option is not implemented in this version of REVIC. After hitting any key, you will be returned to the main menu. THE DISPLAY MENU The next item in the main menu allows you to choose between various displays showing the results of all calculations. DISPLAY MENU - Phase Dist. Display This option will recalculate all results and put up the Phase Distribution Display. This display shows the effort, schedule, staffing, and costs by phase of the lifecycle. DISPLAY MENU - Risk Display This option will put up the Risk Display. This display uses the standard deviation calculated from the lines of code estimates to show the plus and minus three sigma values for effort, schedule, and cost. Use this display to determine the risk position based on the proposed cost for the software development. In a 'fixed price' environment, you would expect the proposed cost to be on the high side of the nominal values, since the contractor is assuming all of the risk. You would normally not expect the proposed costs to be above the three sigma values. In a 'cost plus' environment, you would expect the proposed cost to be on the low side of the nominal values, since the government is assuming most of the risk. If your estimates and the proposed costs vary greatly, you should investigate the possibility that your basic assumptions concerning line of code estimates (and the standard deviation) or the proposed development environment are incorrect. DISPLAY MENU - Activity Display This option puts up a display showing the effort in the system engineering and development phases distributed by the types of personnel doing the work.Distributions of effort in the DT&E phase are not shown. See Dr. Boehm's book for a discussion of the types of activities and limitations of this display. DISPLAY MENU - Maintenance Display This option puts up a display showing the effort, number of personnel required, and costs for maintaining the software over a fifteen year period. The costs shown are based on the wrap rate entered in the Select Environment screen and inflated by the yearly inflation rate. Selecting the 'F2' key will print a report of the maintenance display similar to that obtained by using the 'Maintenance Report' option of the REPORTS menu. To change the inflation factors, use the 'Inflation Factors' option of the MISC menu. To change the labor rates, use the 'Edit Factors' option of the ENVIRONMENT menu. DISPLAY MENU - CDRL page estimates This option will provide a display showing an approximate page count for the various types of CDRLs specified in DOD-STD-2167A. See the discussion of the CDRL estimates under the REPORTS MENU. THE SLOC MENU This menu allows you to enter new estimates for lines of code or to edit the existing estimates already entered. SLOC MENU - Both New & Adapted Code This option allows you to completely respecify the code modules used in the program's calculations. It completely erases the previous data while all other program variables such as the environmental factors are retained. The program will first put up the new code enter screen. When you select 'ESCape' the adapted code enter screen is put up. The introductory information screens described in Section 3 are not shown. All processing within the screens is exactly as already described in Section 3. SLOC MENU - New Code Only This option is similar to the Both New & Adapted Code option except that it will only put up the new code enter screen. SLOC MENU - Adapted Code Only This option is similar to the New Code Only option except that it will only put up the adapted code enter screen. SLOC MENU - Edit Code Estimates This option allows you to change or delete existing line of code estimates. You can also add additional new code or adapted code modules using this option. You are asked if you want a print out of the existing line of code modules. If you chose the 'Y' option, the program will ask you to put the printer on-line and will then print out all the new code and adapted code modules that are active. All activity in the edit module is controlled by function keys. You have the option of editing an existing code module (F3), adding a new code module (F7), adding an adapted code module (F8), or leaving the edit module (ESCAPE). If you choose to edit an existing module, the program will ask you to specify the index number. Once the data is displayed on the screen, you can edit it as previously described for the new or adapted code enter modules. You also have another function key active. The F5 key will delete the displayed module from the data base. If you select the ESCAPE key while editing a module, the program will not make any changes to the module in the data base before leaving the edit module. Entering an index number that is out of the range of the currently entered number of modules or was deleted will result in an appropriate message. If you choose either the add new code or add adapted code function keys, the program will display the appropriate input prompts and allow you to enter the information as previously described in the enter code module sections. If you select the ESCAPE key while entering a new module, the data will not be entered into the data base. THE BEGIN MENU This menu item provides a scripted method for new users to enter all data necessary to get an estimate. See Section 3 for a thorough discussion. The submenu item associated with this choice provides a descriptive message to direct a new user how to proceed. THE QUIT MENU This menu allows you to quit the REVIC program. The submenu item associated with this choice provides a descriptive message telling you to hit the Return key to quit or to hit the ESCape key to return to the main menu. ADDITIONAL MENU CHOICES The REVIC program provides two additional menu choices which are not shown in the mainmenu or associated submenus. These choices are reached by hitting an ALT key sequence anytime that the mainmenu is active as described in the following sections. CHANGE PROGRAM COEFFICIENTS The coefficients and exponents used by the REVIC program in performing its basic calculations may by changed in this screen. To enter this screen hit the ALT "@" key (actually, just use the unshifted "2" key). You will be presented with a display showing the eight equations, effort and schedule for the four modes, and a descriptive title. Use the cursor keys to move around and change any coefficients or exponents desired. Hitting the "F2" key will enter the data and change the equations in program memory. The new equations will remain in memory only as long as the program. If you quit and start REVIC again, the equations will revert to their nominal values. The descriptive name will be displayed on all results to indicate that non- standard coefficients were used, therefore you must type in a new descriptive name whenever changing the coefficients. The program will substitute the name "Non-Standard Coefficients" for you if you do not change it yourself. A function key is provided to allow reverting to the standard coefficients at any time. Hitting the "F3" key will revert to the standard equations and return to the mainmenu. Hitting the ESCape key will return to the mainmenu without changing the coefficients currently in memory. SAVE PROGRAM COEFFICIENTS The coefficients currently in memory, along with the descriptive name can be saved to a .RDF file by hitting the ALT "*" key (actually the unshifted "8" key). You will be presented with the screen asking you to name the new file. The coefficients and descriptive name will be saved to the file and you will be returned to the mainmenu. The stored file can be opened at any time thru the ENVIRONMENT menu. SECTION 5 - REVIC EVOLUTION CALIBRATION The REVIC model is the subject of an on-going effort to calibrate the total effort and schedule estimates within the DOD community. All users of the model are asked to participate in the data collection process. A sample data collection sheet is provided as an attachment to this user's manual. The sheet asks for the minimum set of data necessary to calibrate the coefficients and factors of the model's equations, and should be filled out after the DT&E phase of the software development is completed. Completed data sheets should be sent to the office that provided the REVIC model. SUGGESTIONS FOR IMPROVEMENTS Please send any comments or suggestions for improvement to AFCMD/EPR ATTN: Mr. Bob Ness Kirtland AFB, NM 87117