7 Source code and literals

This section contains editorial rules on how to write source code:

Section 7.1, “Add multiline source code in a defined sequence (ASM-88)”
Section 7.2, “Use a single backtick before and after inline literals (ASM-43)”
Section 7.3, “Use four space characters per indentation level for source code blocks (ASM-79)”
Section 7.4, “Indent XML attributes in examples (ASM-53)”
Section 7.5, “Formatting of special words (ASM-121)”
Section 7.6, “Add a description for multiline source code (ASM-16)”

7.1 Add multiline source code in a defined sequence (ASM-88)

Elements for multiline source code shall be added in the following sequence:

An anchor (see rule ASM-78)
A caption to express the essence of the source code
A source code block (see docs.asciidoctor.org/asciidoc/latest/verbatim/source-blocks/)
1. An attribute list for the source code
  1. An opening squared bracket [
  2. The source attribute
  3. A comma
  4. A space character
  5. A language attribute (optional, see Table 36)
  6. A closing squared bracket ]
2. A starting delimiter ----
3. The source code shall be of one of the following types:
  1. The source code inserted manually
  2. An include of the source code file (see docs.asciidoctor.org/asciidoc/latest/verbatim/source-blocks/#using-include-directives-in-source-blocks)
4. An ending delimiter ----
A blank line
An optional description (see rule ASM-16)

Table 36. Language attributes
Language	Abbreviation
ASAM OpenDRIVE	xodr
C#	charp
Java	java
Python	python
XML	xml

Exceptions

Source code files may be linked by a hyperlink if they are publicly available.

Example

Code

[#code-1e787b21-eb85-4582-9763-6c2319770928]
.Caption of the source code
[source, xml]
----
<junction name="" id="1">
    <connection id="0" incomingRoad="2" connectingRoad="4" contactPoint="start">
        <laneLink from="-1" to="-1"/>
    </connection>
    <connection id="1" incomingRoad="3" connectingRoad="5" contactPoint="start">
        <laneLink from="-1" to="-1"/>
    </connection>
</junction>
----

Result

Code 2. Caption of the source code

<junction name="" id="1">
    <connection id="0" incomingRoad="2" connectingRoad="4" contactPoint="start">
        <laneLink from="-1" to="-1"/>
    </connection>
    <connection id="1" incomingRoad="3" connectingRoad="5" contactPoint="start">
        <laneLink from="-1" to="-1"/>
    </connection>
</junction>

Source

ASAM specific rule.

7.2 Use a single backtick before and after inline literals (ASM-43)

Use a single grave accent U+0060, also called backtick, (`) before and after inline literals.
Do not use pairs of double backticks (``).

In AsciiDoc, double backticks are used for text formatting in certain cases. Unfortunately, this causes poor wording and readability and therefore shall not be used.

Exceptions

There are no exceptions.

Example

Code

`term`

Result

term

Table 37. Use a single backtick before and after inline literals
No	Yes
The example below shows the structure of an ``Act``.	The example below shows the structure of an `Act`.
Movements of vehicles in ``Act`` are defined in the ``ManeuverGroup`` ` s section.	Movements of vehicles in `Act` are defined in the section `ManeuverGroup`.

Source

ASAM specific rule.

7.3 Use four space characters per indentation level for source code blocks (ASM-79)

Do not use tab characters.

Exceptions

In case of a high number of indentation levels, the indentation for an entire source code block can be reduced to two space characters, so that longer text does not result in additional line breaks.

Example

No Yes

Table 38. Use of four space characters per indention level (space characters marked as '.')
No	Yes
`<planView> .<geometry x="-0.014" ...........y="-0.055" ...........hdg="2.88" ...........length="95.89" ...........s="0.0"> ..<arc curvature="-0.000490572"/>`	`<planView> ....<geometry x="-0.014" ..............y="-0.055" ..............hdg="2.88" ..............length="95.89" ..............s="0.0"> ........<arc curvature="-0.000490572"/>`

<planView>
.<geometry x="-0.014"
...........y="-0.055"
...........hdg="2.88"
...........length="95.89"
...........s="0.0">
..<arc curvature="-0.000490572"/>

<planView>
....<geometry x="-0.014"
..............y="-0.055"
..............hdg="2.88"
..............length="95.89"
..............s="0.0">
........<arc curvature="-0.000490572"/>

Source

ASAM specific rule.

7.4 Indent XML attributes in examples (ASM-53)

If XML attributes in examples lead to extra long lines, insert line breaks and indent the XML attributes to form a column under the first XML attribute.
Place one XML attribute per line.

Exceptions

There are no exceptions.

Example

No Yes

Table 39. Indent XML attributes in extra long lines (space characters used for indention marked as '.')
No	Yes
`<planView> ....<geometry x="-0.014" y="-0.055" hdg="2.88" length="95.89" s="0.0"> ........<arc curvature="-0.000490572"/>`	`<planView> ....<geometry x="-0.014" ..............y="-0.055" ..............hdg="2.88" ..............length="95.89" ..............s="0.0"> ........<arc curvature="-0.000490572"/>`

<planView>
....<geometry x="-0.014" y="-0.055" hdg="2.88" length="95.89" s="0.0">
........<arc curvature="-0.000490572"/>

<planView>
....<geometry x="-0.014"
..............y="-0.055"
..............hdg="2.88"
..............length="95.89"
..............s="0.0">
........<arc curvature="-0.000490572"/>

Source

ASAM specific rule.

7.5 Formatting of special words (ASM-121)

In continuous text of standards special words that are contained in the following sources shall be highlighted:
- APIs
- Protocols
- Single-line source code
- UML models
- Schema files, for example, json schema files and XSDs
Do not use the plural of special words.
The following special words shall be formatted:
- Attributes
- Classes
- Data types
- Elements, for example, XML elements
- Enumerations
- File names
- Interfaces
- Keys
- Methods
- Parameters and their values independent of the data type
- Properties
- Single-line source code
The following formats shall be used:
- Use a single grave accent U+0060, also called backtick, (`) before and after special words and single-line source code.
- Do not use pairs of double backticks (``).
- XSD parameters and XML elements shall be surrounded by angle brackets <> and backticks ``, for example, <junction> element.

Value assignments should be written in the form ParameterName = ParameterValue.

Exceptions

This rule does not apply if a special word is the only content in a heading.
General terms contained in section Terms and definitions shall be formatted as described in rule ASM-70.
Multiline source code shall be formatted as described in rule ASM-88.

Example

Code

Any configuration of a measuring list will be announced with a request `RT_START_STOP_MEASURING` (`MEASURING_MODE` = `CONFIGURE`), which is seen as the beginning of a measuring configuration.

Result

Any configuration of a measuring list will be announced with a request RT_START_STOP_MEASURING (MEASURING_MODE = CONFIGURE), which is seen as the beginning of a measuring configuration.

Source

ASAM specific rule.

7.6 Add a description for multiline source code (ASM-16)

The description should be below the source code.
The description shall start with the text [Reference to source code] shows.
The description shall not have an initial article.
The description shall not contain references to the placement of the source code, for example, before or below.
A reference to source code shall be realized by a source code anchor. Source code references are displayed as a link.

Exceptions

There are no exceptions.

Example

Code

<<code-d1e35ab4-dc8d-4013-ae12-4e700dc89a02>> shows an example of an http request.

Result

Code 58 shows an example of an http request.

Source

ASAM specific rule.