9.2 Formatting ASAM OpenSCENARIO code

9.2.1 Coding style guide

This coding style guide is intended to help you write source code in the ASAM OpenSCENARIO domain-specific language in a uniform way.

9.2.1.1 Introduction

This guide focuses on uniform formatting and naming for source code. It does not contain best practices nor is it a reference for the language.

You should follow the recommendations in this document if you are a scenario developer writing scenarios for real use.

By following the recommendations in this guide the code becomes easy to understand for you and other users.

9.2.2 Formatting

9.2.2.1 Indentation

  • Use four space characters per indentation level.

  • Do not use tab characters.

  • Use the following text editor settings:

    • Tab size: 4

    • Insert spaces

9.2.2.2 Encoding

  • Use UTF-8 as encoding.

9.2.2.3 Whitespace

Whitespace characters provide better readability when used in the correct places.

The correct use of space characters within ASAM OpenSCENARIO source code is as follows:

  • One space after a comma (in argument lists and other lists)

  • One space after a colon (for example for inheritance)

  • One space before and after a keyword

  • One space before and after an operator

  • No spaces before and after brackets and braces (for example, in function calls or for indexing)

  • No space between value and unit

The following code snippet shows some examples of the correct use of space characters.

Code 83. Correct use of space characters
func(arg[1], arg2)
if x == 4: print x, y
foo == [x, y, z]
func(1)
abc[key] = lst[index]
i = i + 1
actor bus: car(category: bus):
   keep(width == 1.8m)
   keep(length == 4.5m)

swerve_story: serial:
    side_vehicle.drive() with:
        path(s_side_vehicle)
        keep_speed()
    with:
        until (top.time > 5sec)

9.2.2.4 Comments

  • Single lines of comments and inline comments can be added using the 'pound' symbol (#).

    # This is a single line comment.
    i = i + 42  # This is an inline comment

  • Blocks of comments can be simulated by using several single lines of comments.

    # This is a block of comments example.
# The following call to foo is commented out
# Reason: see issue xyz
# More explanation here...
#
# foo()

9.2.2.5 Line breaks

  • Consider breaking up statements that are too long to fit into one line.
    Use the line continuation special character 'backslash' (\) for marking the continuation.

    This is a line of text that is too long for a single \
line, so continue after the backslash in a new line.

9.2.3 Naming

Naming conventions are a widely discussed topic with great influence on readability influenced by fashion changes, habit, and personal taste.

Here are the recommendations valid for naming conventions in ASAM OpenSCENARIO source code.

9.2.3.1. Use snake_case only

  • Use snake_case (aka lowercase_with_underscore) for all source code elements that are not keywords.

Code 84. Example for correctly formatted code
# 1: Define an actor
actor car_group:
     average_distance: length
     number_of_cars: uint

# 2: Define a road element struct
struct geometric_road: road_element:
    min_radius: length
    max_radius: length
    side: av_side

# 3: Define a scenario
scenario dut.traverse_junction_at_yield:
    s: road_with_sign with(sign_type: yield)
    do dut.car.traverse_junction() with: ...

# 4: Define a containing scenario
scenario dut.mix_three_dangers:
     weather_kind: weather_kind
     keep(weather_kind != clear)
     do mix:
         cut_in_and_slow()
         traverse_junction_at_yield()
         weather(kind: weather_kind)

9.2.3.2 Single character names

Do not use the following characters as single character names because they can be easily misread as zero (0) or one (1):

  • No single lowercase 'el' (l)

  • No single uppercase 'eye' (I)

  • No single lowercase 'oh' (o)

  • No single uppercase 'oh' (O)

If you cannot find a recommendation for your source code formatting or naming problem in this chapter, follow the Style Guide for Python Code (PEP 8).