Program Explanation
An explanation is a description of how a variables value is calculated. Explanations are recreated from information that is logged while making the calculation.
An explanation is used for,
- Understanding why a particular calculation was made.
- Extracting data necessary to set up regression tests.
If the tester, or end-user sees a value displayed which they question, they may select a menu entry that displays an explanation. The explanation traces the calculation back to the source values.
If the user believes the calculation is incorrect, all the log information, related to the calculation may be extracted and sent to the developer for analysis. The extraction will attempt to be generous and send all related log information as well the data.
The developer will be provided with a tool that automates the construction of a regression test from the log information,
- XML file setting up the data for the test.
- A script that performs the test.
Logging the information necessary to construct takes resources. The developer may select which fields need explanation, and only enable explanation on those fields.
Contents |
[edit] Detail
An explanation traces the calculation of a variables value back to constants or values that come from outside the program (e.g. the database or the user). If an explanation is requested in the code, calls will be added to the code that log sufficient information to recover the explanation.
This is done in the partial evaluation phase. A call to the GetExplanation requests an explanation to be created. This causes function calls that log sufficient information to create the explanation to be added. These functions write information to the log.
An explanation for a variable may be defined recursively as,
- If a constant, the value of the constant.
- If calculated by a primitive function.
- The name path of the primitive function.
- Explanation of the other parameters.
- value of the parameter
- If a parameter passed in from outside the project (without explanation).
- The identity of the external function.
- The name of the parameter
- value of the parameter
The programmer may define a function as primitive in which case a log entry will be created for the call. The primitive function may define the explanation to be logged. Primitive functions called by a primitive function are not logged.
Functions that iterate through records will not ask for an explanation of an index into a vector or an array, as such an explanation will not normally be useful. Only the index value will be logged.
The ORM will define primitive functions so that explanations obtained from result sets are,
- If for a column in a result set.
- The column name
- Explanation of the row in the result set.
- If for a row in a result set.
- Explanation of the result set.
The Save method will log the data saved to the database. An explanation id will be included in the log if the attribute requires it. Also "request for explanation" may be enabled on a field, when enables a menu option for display of the explanation of the field value in a form.
The developer may also add their own logging information that includes an explanation id. This would be useful when writing reports or data to files. In any of these cases the partial evaluation phase will then include the calls that log explanation information.
A log is also kept of the tasks which are called. This information will be used in creating the regression test.
[edit] Meta Programming
Partial Evaluation is used to work out what logging is required and add it to the code. A call to GetExplanation on a variable causes the explanation attribute of the variable to be requested. The primitive functions that calculated will have calls that calculate the explanation. These calls will log the necessary information to reconstruct the explanation and call GetExplanation on the variables from which the value is calculated.
The explanation attribute does not actually hold and data itself. But requesting the explanation attribute triggers the logging of sufficient information from which to construct the explanation.
[edit] Logging
A high speed logging system would be required to efficiently implement explanations. The logging system should be designed to have minimal impact on the running of the program. It would write its data to memory for another process to pick up and write to disk.
Each log record consists of,
- time
- process id
- record type
- data
Explanations are identified in the log by an explanation id. The id identifies the variable being explained.
Each calculation for a variable whose explanation is requested has explanation information logged,
- Id identifying the function being called.
- Explanation Id for the variable being calculated.
- Explanation information for each paramameter used in calculating the value.
Each record extracted from the database is recorded in the log. Its data would consist of,
- Explanation Id for the query that extacted the data.
- List of column id, value pairs.
Each record written to the database is also recorded in the log. Its data would consist of a list of,
- Column name
- Column value
- Explanation Id (if the attribute requires it).
Data written to other external systems (e.g. to reports) would be logged similarly.
