Coding Standards for Open Source Modelica

This document contains a coding standard for RML in the Open Source Modelica compiler project.

General Indentation, Layout

All lines should have a maximum of 80 characters
Emacs rml-mode indentation should be used. (Add nicely idented example here)

Long patterns should be avoided. For instance

rule	<premises>
-----------------
evaluate_expr(IALG(Absyn.ALGORITHMITEM(Absyn.ALG_ASSIGN(Absyn.CREF_IDENT(ident, []), exp),_)),st as SYMBOLTABLE(p,_,_,_,_))

could be rewritten as

	rule expr2 = Absyn.ALGORITHMITEM(Absyn.ALG_ASSIGN(cref, exp),_)) &
		cref = Absyn.CREF_IDENT(ident, []) &
<premises>
-----------------
evaluate_expr(IALG(expr2, st as SYMBOLTABLE(p,_,_,_,_))

Comments

Comments containing two ‘*’ will be standard text in the automatic report generation.
All relations should have a preceding comment (with two stars ‘(**’), explaining in general what the relation does. The comment should contain a “Created by” row describing the author of the relation and which version the relation was created in. Below is a good example on how extensive the comment should be:

(** relation: inst_var
 ** author: x97davka (1.1)
 **
 ** A component element in a class may consist of several subcomponents
 ** or array elements.  This relation is used to instantiate a
 ** component, instantiating all subcomponents and array elements
 ** separately.
 **)

Complicated rules should be commented as follows:

(**  A component
 **
 ** This is the rule for instantiating a model component.  A
 ** component can be a structured subcomponent or a variable,
 ** parameter or constant.  All of these are treated in a
 ** similar way.
 **
 ** Lookup the class name, apply modifications and add the
 ** variable to the current frame in the environment. Then
 ** instantiate the class with an extended prefix.
 **)
	
rule	Prefix.prefix_cref(pre,Exp.CREF_IDENT(n,[])) => vn &
...

Each file should contain the following comment structure (which will be extracted in the automatic report generation):

(**
 ** file:	 inst.rml
 ** module:      Inst
 ** description: Model instantiation
 ** author: x97davka
 **
 ** RCS: $Id$
 **
 ** This module exports only one relation. 
 **)

Automatic code generation options:
file, module description, relation, purpose, fixme, rcs, author
can be used as headers to the report generation. These should then be used in comments with two stars ‘(** … **)’

Error and Debug Messages

Error messages from the compiler has the following syntax:

#Error instantiating class foo on line 23, component type Resistor not found

Internal compiler errors should be a trace call of a subset of the relations called when the error was found. For example:
- inst_element failed
- inst_class failed
- inst_class_in_program failed
This means that each of the more important relations should have a final rule which failes that print such error message.

Programming Style

Avoid using booleans in datatypes for special purpose flags in the abstract syntax. Instead, use specific datatypes for each such case. For instance, encapsulated is a typical flag for a Class datatype. Therefore we create the datatype

datatype Encapsulated = ENCAPSULATED | NON_ENCAPSULATED

and then use this one in the Class datatype.

Pattern variables should be self-explanatory, such that the reader can guess what datatype the pattern variable has. For instance:

get_variable_list(expr) => varlst

This recommendation can be relaxed when writing many rules in a relation with similar purpose. The first rule of the pattern should then have more understandable pattern variable names, whereas following rules can have more cryptic pattern variable names. In Short: Use Common Sence.

Relation names should have the following form (lowercase and underscore between words):

get_variable_list, inst_var, get_nth_component_item

Back to OpenModelica Developer Notes