Visual Prolog best practice contains style suggestions and recommendations as used by Prolog Development Center (PDC), when writing programs in Visual Prolog.
The description is intended for use with new Visual Prolog code, and PDC does not expect to update existing code to follow these standards. Therefore, you might see code in Visual Prolog distributions that does not follow these standards.
- The clauses of a predicate should normally occupy less than 20 lines. Otherwise you should consider introducing auxiliary predicates to handle sub-tasks. Situations, where a predicate can occupy more than 20 lines, are the cases, where e.g. 50 properties have to be set for some object each setting requiring a call.
- Use fully qualified names (e.g. someClass::method), whenever that makes the program more clear.
- Class methods should have meaningful names, when read together with the class name. Avoid repeating the class name in the method name, i.e. the name should be:
- A predicate should only do one thing. So, if you have a predicate that does something with every element in a list, consider splitting it into two predicates: one that goes through the list and one that does something with the element. The advantage of doing this is that the predicates become simpler (and thus easier to get correct and easier to understand).
- In general if one side of "=" is a variable then: put it right if it is bound.
You should only use a Boolean if you have something which is either true or false. You should not use it to distinguish between two different cases like left or right, or horizontal or vertical. In these cases you should use specialized domains instead.
domains direction = left; right. orientation = horizontal; vertical.
When you have a Boolean variable name it after the "true"-condition. Thus, a variable that expresses that something is published if it is true and not published if it is false should be called Published.
Cut (i.e. !) is a predicate which "cuts" away nondeterminism, i.e. "cuts" away the possibility for further solutions (hence the name).
The nondeterminism it cuts away can be divided into two groups (though some cuts will fall into both groups):
- Cut's that cut away the possibility to backtrack into a subsequent clause of the current predicate.
- Cut's that cut away further solutions to a nondeterministic predicate call.
There are no other (sensible) uses of a cut, except for the two mentioned above. Once these purposes are understood it is easy to put cuts in the right place:
- Either the cut is put at a place where backtrack to subsequent clauses is no longer wanted, or/and
- It is put after the call of a nondeterministic (i.e. nondeterm or multi) predicate call, for which only a single solution is important.
The first purpose can be illustrated by the following example:
clauses p(17, X) :- X > 13, !, q(X), ... p(A, X) :- ...
In this example we have a cut after the test for X > 13. This is a very typical sound use of the first reason: "Our clauses cases out on the input and now (where now is immediately after the test X > 13), we have found the right case".
Such a cut is typically placed just after the head of the clause or after a test close to the head of the clause.
The second purpose can be illustrated by the following example:
clauses firstMember(X, L) :- X = list::getMember_nd( L), !.
In this example the cut is placed immediately after a nondeterministic predicate, of which we are only interested in a single solution.
Above I have highlighted the word immediately twice, and this is because the keyword in placing cuts is immediately: they should be placed as early in the clause as possible.
You should be suspicious about clauses containing more that one cut. More than one cut in a single clause often signals a programming or design error.
Red and Green Cuts
We do not generally encourage that cuts are turned green; it is perfectly fine with red cuts.
The society of traditional Prolog, has defined the notion of red and green cuts. Briefly speaking a green cut is a cut, which does not change the semantics of the predicate in which it occurs, whereas a red one does change the semantics.
Clearly all the cuts which cut away further solutions from a nondeterministic predicate are red by nature. So distinguishing between red and green cuts only has a purpose for those cuts, which prevents backtracking to next clauses.
Consider the clauses:
clauses p(X) :- X > 0, !, ... p(X) :- X <= 0, ...
The cut in the predicate above is green, because if we remove it the predicate will behave in the same way. When the cut is present in the first clause, the test X <= 0 in the second clause is not really needed:
clauses p(X) :- X > 0, !, ... p(X) :- ...
Without this test the cut is, however, turned red, because now the predicate will behave different if we remove the cut.
Green cuts might seem superfluous, but in fact they are used to remove superfluous backtrack points (mainly for performance reasons). In Visual Prolog they may however also be needed to "convince" the compiler that some predicate has a specific mode (e.g. procedure).
Dispatching on Input Patterns
Only handle very simple things in a dispatcher. The problem with handling stuff in a dispatcher is that it has a very flat structure and typically a lot of different things has to happen. So code that belongs logically together gets spread and pieces of code that basically has very little to do with each other stands next to each other.
To avoid this code that belongs logically together should be placed in handling predicates that are grouped in a module so the dispatcher only calls the handling predicates. This way the dispatcher is just that a dispatcher and code that belongs together are placed close together.
- If a predicate handles many cases then keep each case simple.
- Never have more clauses for the "same case", if the predicate also handles "other" cases.
The first "rule" is straight forward. The second rule can be illustrated with the following example:
clauses qwerty(17, W, E, R, 13, Y) :- ..., % A !, ... % B qwerty(17, W, E, R, 13, Y) :- ..., % C qwerty(Q, W, E, R, 13, Y) :- ... % D ...
The clauses section above represents a bad coding style, because it has two clauses for the same input "pattern". This would have been OK if this was the only input pattern the predicate deals with. But in this case, we have clauses for other patterns as well. I think that the predicate above should have been rewritten, such that the purpose of qwerty is solely to case out on the specific patterns of input leaving other work to sub-predicates:
clauses qwerty(17, W, E, R, 13, Y) :- !, % we have cased out, this is one of our cases qwerty_17_w_e_r_13_y(W, E, R, Y). qwerty(Q, W, E, R, 13, Y) :- !, % we have cased out, this is one of our cases qwerty_q_w_e_r_13_y(Q, W, E, R, Y). ...
clauses qwerty_17_w_e_r_13_y(W, E, R, Y) :- ..., % A !, ... % B qwerty_17_w_e_r_13_y(W, E, R, Y) :- ... % C
clauses qwerty_q_w_e_r_13_y(Q, W, E, R, Y) :- ... % D
This code has changed the qwerty predicate into a predicate, which only cases-out on the various combinations of input. It is not essential that you only have a single predicate call for each kind of input as illustrated above. The main point is that you do not back-track from one clause to another on the same input pattern.
This rule does especially apply to event handlers, you should not have more than one clauses for "close" (or anything else) in the same event handler. An event handler often spread on several pages, so if it is not a rule that each case is handled by a single clause, then you will have to look at all clauses to be sure that you know how a single input pattern is handled.
Exceptions and Error Handling
- When an error/exception occurs, raise an exception with exception::raise.
- Trap an exception if you want to handle the exception.
- Use finally if you want to run some code even in the exception case and then continue the exception.
- See also the tutorial about Exceptions handling.
Internal Errors and Other Errors
You should distinguish between internal errors and errors which had to do with the usage of the tool/module/class/unit. If some internal invariant is violated it is an internal error. Typical examples of internal errors are:
- A database fact which should have been defined is not defined.
- A predicate which should be a procedure, but which the compiler could not recognize as such are made into a procedure by adding a fall through clause, if that clause is reached it is because the assumption that the previous clause could not fail (an invariant) was wrong.
Internal errors should share one exception per unit. You should always use an exception: One for each user error and one for internal error (that is one for each unit).
Typical user errors:
- If an index is out of limits
- If a window handle is "wrong"
- If the predicates are called in the wrong order.
There are two reasons why one might want to trap an exit:
- Because one wants to handle the exception, say you open a file and get an exit saying that the file does not exists. In that case you want to trap the exit and display some error message saying that the file does not exists. Of course if the exception was not one of the ones you wanted to handle you have to continue the exception.
- Because you want to do something regardless of whether the predicate exits, a typical example is that you get some kind of lock do something and release the lock. Here you want to be sure that the lock is released also if this something exits. So you use finally.
Mode and flow patterns
By default predicates have procedure mode. You should not write procedure unless you want to stress it for some reason (but in that case you might consider whether the predicate should change name instead).
predicates doSomeThing : (). % do not write "procedure" here
By default all predicate arguments are input. You should not write unnecessary flows.
predicates doSomeThing : (string In1, string In2). % do not write a flow pattern here, when all the flows are input anyway
[in] and [out] can be used directly on arguments. Do not write [in], because arguments are input by default.
predicates doSomeThing : (string In1 /* do not write [in] here */, string Out2 [out]).
If a predicate only have one flow pattern, you should use [out] in favour of flow patterns.
predicates doSomeThing : (string In1, string Out2 [out]). % do not write a flow pattern here when there is only one flow
By default facts are nondeterm. You should not write nondeterm unless you want to stress it for some reason (but in that case you might consider whether the fact should change name instead).
facts personData_fact : (string FirstName, string LastName, string Address). % do not write "nondeterm" here