Navigation  without Java Scripts

 

Visual Prolog 6.x coding standard

This document describes coding standards for Visual Prolog programs, written as part of the Visual Prolog system itself.  It is also the standards for examples in user documentation.  As such it represents Prolog Development Center's suggested coding standards for users as well.

Keywords

Keywords are typed in lowercase letters. In documents keywords are typeset with a boldfaced sans serif font, for example Arial.  Default color is dark yellow.

constants
domains
database
facts
predicates
class
interface
implement
end
inherit
support
open

Semi-keywords

Visual Prolog uses a number of  tokens for diverse syntactical structuring.  These words are all written in lower-case  (except the calling convention C, which is written C) normal faced sans serif font.  These semi-keywords are colored in two different colors depending on their nature.  If the word represent a choice then it is colored purple, whereas if it is a structuring word it is colored dark yellow.

erroneous
failure
procedure
determ
nondeterm
multi
stdcall
C
...
language
as
...

This example show the colors and font

predicates
    myPredicate : (string Value)
        procedure (i) language stdcall as "_myP"

Literals

Literals are colored blue in documents.

1
"Hello world!"

Identifiers

The general format of an identifier can be described by the following EBNF grammar:

<Identifier> = <Prefix> <WordGroups> <Suffix>
<WordGroups> = <WordGroup> { ‘_’ <WordGroup> }*
<WordGroup> = <Word>+

Prefixes and suffixes are used to signal the kind of identifier, and will be dealt with in connection with each kind of identifiers. The words are capitalized, except for those situations where the first letter of the whole identifier has to be lower case.

All variables start with an uppercase letter and everything else starts with a lower case letter.

In documents everything except keywords are typeset in a serif font, for example Times New Roman

Constants

Constants have no prefix or suffix. They start with a lowercase letter.

numberOfRows
pi
logErrorMsg

Variables

Variables have no prefix or suffix. As mentioned (and demanded by Prolog) variables start with an uppercase letter. In documents variables are colored green.

X
File
OutputStream

Predicates

Predicates have no prefix.  Predicates have no suffixes, unless it seems to be necessary in order to avoid confusion. In such cases the following suffixes should be preferred:

_db database functor/predicate
_nd nondeterm/multi
_err erroneous
_fail failure
_det determ
_multi multi

Notice, that normally multi predicates would be suffixed with _nd, but if circumstances demand it _multi can be used instead.

write
setWindowFont
member
member_nd
ganttBar_db

Domains

Domains have no prefix. _list is used as suffix to list domains, in cases where the list domain does not have a (business-)domain name, i.e. a database record is a list of values, but record is a better domain name that value_list, so that is preferred. Notice that domains start with a lowercase letter. This also holds for build in domains like string, integer, etc.

string
integer
value
record
record_list

Classes

Classes have prefix c.

cString
cInputFile
cTemplate

Interfaces

Interfaces no have prefix or suffix, being constants they attar with a lowercase letter.

inputStream

COM interfaces traditionally start with an "I", this "I" kept but converted to lowercase:

iUnknown
iDispatch

Monitors

Monitors have prefix m.

mBatchQueue
mPrinterQueue
mPostBoxes

Formatting

This section considers formatting of program code. By formatting we mean line breaking, indentation and alignment. Indentation refers to the amount of white space at the beginning of the line, where as alignment refers to aligning constructs which are not the first on the line.

Line breaking

Line breaking follows the following rules:
Lines should normally not be longer than 70 characters.
Outer syntactic constructs are always broken before inner constructs.
At least one empty line separates clauses of different predicates.
Clauses of the same predicate are not separated by an empty line.
At least one empty line precedes a section keyword.
Each predicate call in a clause is on a line by itself.
Cut (no matter how tiny it seems) is also on a line by itself.
The head of a clause is on a line by itself.

Indentation

By indentation we mean the amount of white space at the beginning of the line. Indentation follows the following rules:
Indentation is done in equal steps (for example 4 spaces).
If the components of a set of parentheses must be broken on several lines then a line break must be inserted immediately after the opening parenthesis, and the indentation is increased one step (no alignment) with the opening parenthesis.

Alignment

No alignment is used (alignment refers to aligning constructs which are not the first on the line, constructs which are the first on the line are "aligned" by indentation rules).

Space characters

Space after comma.
Space after comma can be omitted inside functors, including lists.
No spaces before or after parentheses, unless the parenthesis is next to a token that is normally surrounded by space, such as ' :-'

Constructs

In this section we shall deal with constructs one by one.

Sections

Section keywords are on a line by itself. If the section keyword is indented n steps then the constructs of the section is indented n+1 steps.   Sections must be separated by at least one empty line.

clauses 
    p.

clauses
    q.

Classes, Interfaces, Implementations, etc

The class opening and class closing is on a line by itself. The closing always include the class identifier, the section keywords inside the class are indented one step more than the class itself.

class cSpecialOutputFile supports cOutputFile
    predicates
        ...
end class cSpecialOutputFile

The same goes for other constructs like class (i.e. interface, implementation, monitor, etc).

Predicate declarations

Predicate declarations always have names for the arguments, these names are formatted as variables.  Mode and flow pattern declarations is optional. 

predicates
    increment : (integer X) -> integer Y
    bubbleSort : (integer_list Input) -> integer_list SortedList
    myPredicate_nd :
       (aVeryLongDomainName StrangeFirstParamanter,
        anotherLongDomainName PlainSecondParameter)
        nondeterm (i,o)
        determ (i,i)

Notice the line break after the opening parenthesis and the ordinary increase in indentation. Also notice the break before the ‘–‘. Either all arguments are on a single line or each of them is on a separate line.

Domains

Functors always have names for their arguments; these names are formatted as variables.  If a domain declaration is broken on several lines then it is first broken after the equal sign.  Either all functors are on a single line or each of them is on a separate line.  Either all arguments of a functor is on a single line or each of them is on a separate line.

domains
    value_list = value*
    value =
        int(integer Value);
        real(real Value);
        str(string Value).
    aVeryLongDomainName =
        x(interger X); y(integer Y).
    anotherLongDomainName =
        aFunctorWithManyArguments(
            integer X,
            integer Y,
            integer Z,
            integer RedColourComponent,
            integer BlueColourComponent,
            integer GreenColourComponent).

Clauses

The clause head is on a line by itself.  Each call in the clauses body is on a line by itself.  If clause head have to be broken then the arguments are indented two steps more than the clause head, because otherwise it would be indented to the same position as the clause body.

clauses
    myPredicate(X, Y) :-
        callNoOne(X, Y, Z),
        !,
        callNoTwo(Z, Y).
    myPredicate(X, Y) :-
        callNoThree(X, Y).

    aPredicateWithManyArguments(FirstArgument, SecondArgument,
            X, Y, Z, ErrorNo, ErrorMsg) :-
        callNoOne(FirstArgument, SecondArgument, X, Y, Z,
            ErrorNo, ErrorMsg),
        callNoTwo(…),
        …

Non-deterministitic loops

A construction that is often used in Prolog is "looping" over the results of a non-deterministic call.  For this construction we propose to indent the "loop body" one extra level:

clauses
    myPredicate() :-
        member(X, [1,2,3,4,5,6]),
            doAction(X), % extra indentation in the "loop body"
        fail.
    myPredicate().

Formatting code in word

This section gives a few hints that make it easier to format code in Microsoft Word.

I have constructed a paragraph style code. And a number of character styles: keywordparameter, var, literal etc

The code paragraph style has the following properties:
It is based on the Body Text paragraph style, which provides correct spacing below a code section.
It turns off proofing (i.e. spell check).
It indents an amount and set the default tab size to the same amount, I use 0,63 cm because this is the default size in other paragraph styles.
It has the keep lines together property set, so that program parts are not split across pages.

The keyword character style changes the font to Arial and the font face to bold and the color to dark yellow, var changes the color to green and finally literal changes the color to blue.

When you type in code you start by selecting the code paragraph style and the type your code using soft line breaks (shift+newline), and tab for indentation (reset the option insert and backspace set left indent on tools -> options … -> edit sheet).

Timesaver: Then double-click one of the keywords and select the keyword character style. With that keyword still selected double-click the format painter (the paintbrush in the toolbar), and then single-click all your keywords one at the time. When all your keywords have been painted press escape or click the format painter again.