REAL Studio Coding Standard
From Real Software Documentation
Contents |
Introduction
This document presents a coding standard for Real Studio.
The purpose of this coding standard is to assist Real Studio developers to:
- Write correct code;
- Write easily maintained code; and
- Understand Real Studio code.
General
Anything that is not obvious should be explained in a comment, at the point where it occurs.
Comment should be preceded by the double-slash // comment delimiter. The single quote character should not be used for general commenting; its use should be reserved only for commenting out code, because Real Studio provides a command to insert and remove the single quote before a block of commands, and doing this will leave // comments untouched.
The purpose of a method should be explained at the top of the method, immediately below the pre- and post-conditions, if those do not provide sufficient documentation (see the example below).
Pre- and Post-conditions
Any method whose purpose and correctness is not very obvious should begin with comments explaining what the program assumes (the Preconditions) and what the method will change in the program’s state (the Postcondition). If possible, these conditions should be described in a way that could be checked by code.
In more detail:
Precondition
The preconditions for a method are aspects of the program’s state that are assumed to be true before the method is run. Except for debugging purposes, the method does not check that the conditions are true, and the method will either fail or work incorrectly if these conditions are not true.
An example:
Postcondition
The postconditions for a method are the aspects of the program state that are changed by the method. Examples are the value returned by a function and changes to data structures, user interface display, or communications (via a network, perhaps).
An example of a full pre- and post-condition (here, w is the argument to the method):
//Pre: Count and Word arrays have same number of elements
//Post: if w is in Word array, the value of Count at the same index is //incremented
// otherwise, w is appended to Word array, and 1 is appended
//to Count array
//ie we are maintaining a count of the words submitted to this method,
//in the two arrays
Loop invariants
Many program errors are due to mistakes in writing loops correctly.
It helps to avoid these errors if we think of a loop as a repeated change in state. Each time through the loop, something is true, it possibly becomes untrue within the loop, then it is made true again by the end of the loop. You should state the loop invariant above the loop, if appropriate, prove that it has been made true at that point, then prove through each possible execution path within the loop, that the invariant is kept true.
There may be several loop invariants. If this is the case, you should label each loop invariant with a name, and refer to these names when you prove them correct.
An example:
//Pre: None
//Post: Word array contains all of the words in Source;
//Count array contains corresponding count of those words in Source
Dim InWord As Boolean
Dim counter, WordStart As Integer
if Len(Source.text)>0 then //If source is not empty
InWord = IsWordCharacter (1)//Inword invariant (below)
If InWord then//Wordstart invariant (below)
WordStart = 1
end if
for counter = 1 to Len (Source.text)
//Invariants:
//Inword: InWord is true if the counter character of Source.text was
IsWordCharacter
//WordStart: WordStart is the last counter character such that the
//character before it was not IsWordCharacter
if InWord then
if not IsWordCharacter (counter) then
AddWord (Mid (Source.text, WordStart, counter-WordStart))
InWord = false //InWord invariant
end if
//WordStart invariant: InWord implies we don't need to change WordStart
else //not InWord
If IsWordCharacter (counter) then
InWord = true //InWord invariant
WordStart = counter //Wordstart invariant
end if
end if
next
end if
