SimTalk 2.0 Style Guide

• 1 Introduction

• 2 SimTalk Language Rules

• 2.1 Default Parameter Values
• 2.2 Referenced Parameters
• 2.3 True/False Evaluations
• 2.4 Strings

• 2.5 Parentheses

• 3 SimTalk Style Rules

• 3.1 Semicolons
• 3.2 Line Length
• 3.3 Indentation
• 3.4 Blank Lines
• 3.5 Whitespace
• 3.6 Naming
• 3.7 Method Length
• 3.8 Type Annotations
• 3.9 Parameters
• 3.10 Default Parameter Values
• 3.11 Return Value Type
• 3.12 Comments and Docstrings

Introduction

SimTalk is a programming language developed by Siemens AG primarily utilized to extend the functionality of Tecnomatix Plant Simulation. It’s important to note that this document is neither affiliated with Siemens AG nor an official release. The guide draws inspiration from the official documentation and example models provided by Siemens AG. With the introduction of SimTalk 2.0, significant changes have been implemented, detailed in the release notes accessible here. SimTalk 2.0 introduces simplified formatting and reduced code, which is why this style guide pertains specifically to version 2.0.

2 SimTalk Language Rules

2.1 Default Parameter Values

It’s permissible to specify values for variables at the end of a function’s parameter list.

param x: string, y: integer := 4

If the method is invoked with a single argument, y will be assigned the value of 4. If it’s called with two arguments, y takes on the value of the second argument.

2.2 Referenced Parameters

As outlined, utilizing “byref” allows for passing parameters by reference, enabling direct access to these parameters, which can potentially affect the calling method. It’s advisable to exercise caution when using referenced parameters due to their complexity in identification and readability. In the absence of programmatically available classes in SimTalk, consider its application only when a custom class instance would be returned in a higher programming language to maintain clarity and coherence.

2.3 True/False Evaluations

Prefer to use worded Boolean comparisons for enhanced readability and clarity in your code. Instead of relying solely on symbols like “=” or “/=”, consider using their worded equivalents such as “not”. This practice makes the code more understandable, especially for those who may not be familiar with symbolic representations.

Yes:
if not isObject(truck)
    return false
elseif isObject(truck)
    return true
end

No:
if isObject(truck) = false
    return false
elseif isObject(truck) = true
    return true
end

2.4 Strings

Utilize the to_str() method for string formatting, even when all parameters are strings. Concatenating two strings with the + operator is permissible. Avoid exceeding this method of string concatenation.

Yes:
x = to_str(“root.”, objectName, “.stats”)
x = object + “.stats”

No:
x = “root.” + objectName + “.stats”

2.5 Parentheses

In SimTalk, parentheses aren’t mandatory for method calls when no parameters are passed. However, they should be employed for methods that don’t function like attributes. Even if the method executes code, it’s treated as an attribute when used in this manner.

Yes:
truck.getColor
truck.driveToHome()

No:
truck.getColor()
truck.driveToHomePosition

3 SimTalk Style Rules

3.1 Semicolons

With SimTalk 2.0 it is not required to terminate lines with semicolons. So don’t do it.

3.2 Line length

3.3 Indentation

When structuring code, it’s recommended to indent code blocks using either a tabulator or four spaces. Consistent indentation enhances code readability and maintains uniformity across projects. This practice also aids in debugging and understanding code structure more effectively. Indent code blocks with tabulator or 4 spaces.

Yes:
if x > 4
    x += 1
end

No:
if x > 4
x + = 1
end

3.4 Blank Lines

Ensure one blank space between top-level definitions, including docstrings or parameters, for clarity and organization. Avoid using blank lines after default operators like if-statements or loop definitions to maintain a clean structure. Utilize single blank lines judiciously within functions to enhance readability and separate logical sections as needed.

3.5 Whitespace

Adhere to standard typographic rules regarding the use of spaces around punctuation marks. Ensure there is no whitespace inside parentheses, brackets, or braces to maintain consistency and readability in code formatting.

Yes:
truck.returnHome(lastStations[1], [Station1, Station2])

No:
truck.returnHome(lastStations[ 1 ], [ Station1, Station2 ])

No whitespace before a comma, semicolon, or colon. Do use whitespace after a comma, or colon, except at the end of the line.

Yes:
if x > 4:
    print(to_str(x, y))
end

No:
if x > 4:
    print( to_str( x , y))
end

No whitespace before the open parentheses / bracket that starts an argument list or indexing.

Yes:
truck.returnHome(4)

No:
truck.returnHome( 4 )

Surround operators of each kind with a single space on either side of the assignment except colons before type annotations. Do not use a whitespace before the colon.

Yes:
x := 4
x > y
x += 10
x: integer := 4

No:
x:=4
x>y
x+=10
x : integer:=4

3.6 Naming

methodName, AttributeName, InstanceName, localVariableName, CONSTANT_NAME

When naming methods and variables, prioritize descriptive names over abbreviations. Avoid ambiguous or unfamiliar abbreviations that may confuse readers outside your project. Additionally, refrain from abbreviating words by deleting letters within them to ensure clarity and understanding throughout your codebase.

In case a method returns a Boolean, tend to name the method “is…”. For example: isFree.

3.7 Method Length

It’s advisable to favor small, focused methods for improved code maintainability and readability. While this approach may seem tedious in SimTalk due to the requirement of each callable method having its own Method object instance, it offers long-term benefits. Although there’s no strict limit, methods exceeding 40 lines should be evaluated for potential splitting to enhance clarity and manageability.

3.8 Type Annotations

With SimTalk, type annotations are essential, and there should be no whitespace before the colon following the variable name. After a whitespace, the type annotation should be placed. For variables with default values, ensure adherence to the whitespace rules for operators to maintain consistency and readability in your code.

Yes:
var variableName: integer
var variableName: integer := 4

No:
var variableName : integer:=4

3.9 Parameters

Position parameter definitions immediately after the docstring without inserting a blank line in between. While it’s feasible to write parameters of the same type without individual type annotations, it’s not advisable. Opt for a type annotation for each parameter separately to enhance clarity and maintain consistency in your code.

Yes:
param x: integer, y: integer, truck: object

No:
param: x, y:integer, truck : object

3.10 Default Parameter Values

Yes:
param x: integer := 4, y: integer := 0

No:
param x: integer:=4, y:integer:=0

3.11 Return Value Type

Specify the type of the return value immediately after the parameter list if applicable, or directly after the docstring if no parameters are required. This ensures clear documentation and comprehension of the function’s behavior and output.

Yes:
-> boolean
OR:
param x: integer := 4, y: integer := 0 -> boolean

No:
->boolean

3.12 Comments and Docstrings

3.12.1 Block and Inline Comments

Comments should be used in tricky parts of code. Do not use the -- operator for comments, instead use //.

// This section calculates the minimum distance
var distance:length := 4 // Minimal distance is 4

distance += (truck.speed / 10) * (truck.speed / 10) // Basic formula for braking distance

3.12.2 Docstrings

For every method featuring non-obvious logic or significant size, include a docstring at the top of the source code. This docstring should offer adequate information to call the method without the need to delve into its source code. The docstring format comprises a trailing blank comment line followed by a concise description of the method’s purpose, concluding with a trailing dot.

The only mandatory part is the method description. Judge if the rest is required.

//
// Calculates the minimal distance required between two trucks and humans.
//
// Parameters:
// x: the current distance to another truck.
// y: the current distance to the closest human.
// truck: the current truck.
//
// Returns:
// Returns the minimal distance required between two trucks and humans.
//
// Raises:
// RuntimeError: No truck is given.

3.12.3 TODO Comments

Employ TODO comments to denote sections of code that are temporary, short-term solutions, or deemed “good-enough” but not perfect. This practice helps identify areas needing improvement or future attention while maintaining code clarity and progress.

// TODO: Calculate track length instead of estimating