From 88ea0767561d3c0efd33f01bc234a95bc5e8c0c6 Mon Sep 17 00:00:00 2001 From: Erik Jaegervall Date: Mon, 18 Sep 2023 10:48:25 +0200 Subject: [PATCH] Make naming rules more strict This is a proposal for discussion Signed-off-by: Erik Jaegervall --- docs-gen/content/rule_set/basics.md | 23 +++++++++++++++---- .../content/rule_set/data_entry/allowed.md | 2 +- 2 files changed, 20 insertions(+), 5 deletions(-) diff --git a/docs-gen/content/rule_set/basics.md b/docs-gen/content/rule_set/basics.md index dd932dbc1..b20ba469d 100644 --- a/docs-gen/content/rule_set/basics.md +++ b/docs-gen/content/rule_set/basics.md @@ -103,14 +103,30 @@ Vehicle.Navigation.CurrentLocation: It is recommended for servers, which are implementing protocols for the vehicle signal specification, to serve old and new nodes during the deprecation period described above. +## Naming Rules + +Different languages and environments have different rules for identifiers. +To simplify usage of VSS in as many languages and environments as possible the following rules apply. + +* The allowed character set for node names (branches and signals) is `A-Z`, `a-z` and `0-9` +* Node names must not start with a digit +* Names are case sensitive, but it is not allowed to have two nodes that only differ by case, + i.e. it is not allowed to have both `Vehicle.Aaa` and `Vehicle.AaA` +* It is not allowed to reuse the same node name as a parent node in a child node, + i.e. it is not allowed to have a node `A` if a parent grand parent also is called `A`, like `A.B.A` +* For string literals only the characters `A-Z`, `0-9` and `_` are allowed, + and the value must start with `A-Z`. See the [chapter](/vehicle_signal_specification/rule_set/data_entry/allowed/) for specifying allowed values. + +It is recommended that VSS Tools shall give an error if the rules above are not followed. + ## Style Guide -The VSS specification must adhere to YAML syntax. To keep the standardized VSS specification in this repository consistent the following style guide is provided. +For a contribution to VSS standard catalog the following recommendations must be followed: ### Naming Conventions -The recommended naming convention for node elements is to use camel case notation starting with a capital letter. It is recommended to use only -`A-Z`, `a-z` and `0-9` in node names. For boolean signals it is recommended to start the name with `Is`. +The recommended naming convention for node elements is to use camel case notation starting with a capital letter. +For boolean signals it is recommended to start the name with `Is`. Examples: @@ -118,7 +134,6 @@ Examples: SomeBranch.AnotherBranch.MySignalName Vehicle.Cabin.Door.Row1.Left.IsLocked ``` -Naming convention for string literals can be found in the [chapter](/vehicle_signal_specification/rule_set/data_entry/allowed/)for specifying allowed values. ### Line Length diff --git a/docs-gen/content/rule_set/data_entry/allowed.md b/docs-gen/content/rule_set/data_entry/allowed.md index 12b329c47..aba956666 100644 --- a/docs-gen/content/rule_set/data_entry/allowed.md +++ b/docs-gen/content/rule_set/data_entry/allowed.md @@ -27,7 +27,7 @@ in a list. Only values can be assigned to the data entry, which are specified in this list. The `datatype` specifier gives the type of the individual elements of the `allowed` -list. In general `allowed:` is valid for all datatypes, including integer- and float-based types, unless othwerise specified. +list. In general `allowed:` is valid for all datatypes, including integer- and float-based types, unless otherwise specified. ## Recommendation on String values