Below are miscellaneous comments and remarks on Module Interface Specifications (MIS), their organization and their contents. The order of these comments is not particularly significant.
Keep it simple and systematic: Many mathematical expressions in your MISs are unnecessarily complicated. This will lead to unnecessarily complicated expressions in your MIDs and, in turn, to unnecessarily complicated programs. Unnecessarily complicated programs take unnecessarily long to design, inspect and test, and they tend to have a high error rate. You will have to use too much of your brain power to overcome unnecessarily complicated expressions and programs, leaving too little brain power to actually solve the problems. Eliminate unnecessary complexity at the very beginning and you will have more brain power to solve the actual problems, you will finish earlier and you will make fewer mistakes, perhaps even none.
So, go over your MIS again, eliminate unnecessary complexity and clean it up in preparation for making your MID.
Naming variables and routines: Variables stand for values and values, in turn, represent static things, properties, characteristics, etc. Routines, on the other hand, typically define actions. Usually, therefore, it is appropriate to
Examples of names of routines in the player modules based on verbs of action are InitGame (abbreviated for "initialize game"), InformPlay (for "inform about previous play"), DealToTable ("deal a card to the table"), etc.
Function procedures return a value and therefore their names have more the character of variables than actions. It is usually most appropriate to name function procedures as variables. In fact, in some object oriented languages one cannot tell the difference between the name of a variable and the name of a method (function procedure) from outside the object; whether the name is that of a variable or of a method is a secret of the object and can be changed without having to change anything outside the object.
Modularizing long expressions: When modularizing a long expression by dividing it into subexpressions and replacing the subexpressions by newly defined mathematical functions, define such functions to be completely self-contained. I.e., list all free variables in the subexpression as formal parameters (arguments) of the function. Every free variable in the expression defining the function should be a formal parameter of the function. This applies also to variables whose values are functions. Examples of such variables with functions as values are the functions mapping a suit to a color and a symbol to the two possible score values.
Numerical constants: Be particularly careful that no numbers or other constants related to parameters of the game or other aspects of the environment creep into the mathematical expressions in your MIS, MID, etc. The numerical constant 1 is a frequent exception because of its special role in arithmetic, but even with this constant one should be very careful. Any constant other than the number 1 is highly suspect and is almost certainly inappropriate. In the case of the game of Sevens, the constants 7 and 10 may creep in, but even these should be replaced by named constants. The specification of the interface between the MCP and the player modules has been changed to require that these constants be referred to only by name in player modules.
MIS Header: Note that the first section of the MIS deals with the module as a whole and not exclusively with any access routine in particular. This section contains a list of imported identifiers (names), exported identifiers (names), state variables, the state invariant and assumptions. The assumptions deal with overall aspects of the module, and usually stipulate that one particular initialization access routine must be called before any other access routine. Avoid stipulating unnecessarily restrictive assumptions.
Access routine semantics: Subsequent sections of the MIS deal with the access routines, one section for each access routine. Each access routine's section contains only three pieces of information: (1) the name of the access routine, (2) a relation between the values of relevant variables before and after execution of the routine (an input/output relation), and (3) a statement of restrictions on the use of the access routine. The statement of restrictions on use normally takes the form of a mathematical expression defining the domain of the access routine, i.e. the set of values of the input variables for which the effect of executing the access routine will be defined. The statement of restrictions may, alternatively, define exceptions in using the access routine, in which case, it must be stated what is to be done if the exception condition(s) apply.
"Assumptions" belong to the header information, not to the access routine semantics.
Imported and exported identifiers: These are names that are defined (declared) in one module and referred to in another. Among the exported identifiers are the names of the access routines (e.g. "T45InitGame"). The formal parameter list is not part of the exported identifier (i.e. the exported identifier is not "T45InitGame(NumberOfPlayers, PlayerID").
Mathematical expressions: Mathematics is a pedantically precise and unambiguous language. The very properties of the language of mathematics we need in engineering depend totally on that pedantic precision and unambiguity. The least bit of sloppiness or imprecision in our use of the language of mathematics makes it useless for our purpose. Extreme attention must be paid to rules of syntax, type compatibility, etc., when formulating expressions. Watch carefully the domain and range of every function used in your mathematical expressions and make sure that you use them consistently. Just as "John and go" is wrong in English grammar (the conjunction "and" must connect like things, and the noun "John" and the verb "go" are not like things and, therefore, cannot be connected with the conjunction "and"), the would-be expression "3+{'ab', 'cd'}" is not a valid expression in the language of mathematics (the addition function + maps a pair of numbers to a number, and the subexpression "{'ab', 'cd'}" is not a number).
Ensure that your expressions and your notation reflect the meanings you intend. If you intend a numerical variable to be restricted to the integers, either write that restriction explicitly or verify that this restriction is implied by other parts of your expression. Remember that the notation [1, 1000] in general means the set of all (including real) numbers between 1 and 1000 inclusive. If you write "xÎ[1, 1000]", keep in mind that many non-integers (e.g. 3.56) for the value of x satisfy this condition.
Similarly, be sure to include in your input/output relations for access routines all conditions that the values of variables are required to satisfy, e.g. conditions following from the rules of the game. When writing such input/output relations ask yourself, "Will all values returned to the main control program and satisfying my input/output relation be accepted by the main control program as valid?" If the answer is no, your input/output relation is too weak.
For further information on formulating mathematical expressions, see Translating English to Mathematics at http://www.cas.mcmaster.ca/~baber/Courses/General/EnglToMath.pdf.
State variables: That part of the MIS header dealing with state variables should give the name of each state variable and a brief description of what it is and its meaning (interpretation). Be careful not to include additional information on the state variables here that really belongs somewhere else, such as in the state invariant.
Bounds on values of state variables often belong to the state invariant, not to the description of the state variable in question.
Types of state variables and other variables: Use mathematical objects and types in ways that correspond to their interpretations in the application domain. For example, in the game Sevens, the order in which cards were played onto the table is of significance, so representing the cards on the table as a sequence (rather than as a set) is appropriate. In the case of cards in a player's hand, the order in which they were dealt or the order in which they are organized in the hand is not significant; it has no bearing on what may or may not happen or be done in the future. Therefore, it would be appropriate to represent the cards in a player's hand as a set, not a sequence. Representing the cards in a player's hand as a sequence would, in effect, impose an additional structure that does not correspond to any aspect of the game.
If some collection of information constitutes, in essence, a function or a relation, represent it with a state variable that is a function or relation. Remember that a relation is a certain kind of set (which kind?) and that a function is a special kind of a relation and, hence, also a set.
State variables and formal parameters in access routines: Note that in Oberon-2 (and in most comparable programming languages), a state variable may not be used as a formal parameter for a routine (procedure). (A formal parameter is either a value parameter and hence a local variable or a variable parameter and hence a variable in the calling environment; a state variable is neither.) Therefore, in the section on access routine semantics, the names of all formal parameters must be different from the names of state variables, so make sure that no name of a state variable appears as a formal parameter in the section on access routine semantics.
Input/output relations and domains: Every input/output relation and every domain must be given in an MIS in the form of a mathematical expression, i.e. must be written in the language of mathematics. If you have any English sentence or phrase in an input/output relation or domain, you are not finished translating your text into mathematics.