search

COVESA / vehicle_signal_specification

Vehicle Signal Specification - standardized way to describe automotive data
Mozilla Public License 2.0
307 stars 157 forks source link

Improve naming convention to distinguish instances from branches #749

Open jdacoello opened 1 week ago

jdacoello commented 1 week ago

The current property naming convention can cause confusion when several branches exist, as it uses the same dotted notation for both branches and instances.

Simple scenario

For example, the property name Vehicle.Cabin.Door.Row1.DriverSide.Window.Position does not clearly differentiate between the Row1.DriverSide being an instance of the Door feature of interest, versus a branch in the property hierarchy.

To address this issue and improve the clarity of the property naming convention, the following two alternatives are proposed:

  1. Using Distinct Symbols to Enclose Instances: Example: Vehicle.Cabin.Door[Row1.DriverSide].Window.Position. In this approach, a set of distinct symbols, such as square brackets [ ], are used to enclose the instance information, making it visually distinct from the branch names. The specific symbols used (e.g., [ ], { }, - -etc.) can be determined based on team preference and overall consistency.
  2. Using a Separate Instance Identifier: Example: Vehicle.Cabin.Door.Instance[Row1.DriverSide].Window.Position In this approach, a separate identifier, such as the keyword Instance, is used to explicitly indicate that the following information represents the instance of the feature of interest Door. The instance information is then enclosed in a set of distinct symbols, similar to the first solution.

The goal of these proposals is to maintain the simplicity of the dot notation for branch names, while providing a clear visual distinction for the instance information. This will improve the overall readability and understanding of the property naming convention used in the codebase.

Complex scenario

What about cases when multiple branches are instantiated to specify the property of a feature of interest? For example, a vehicle can have multiple instances of a Door (e.g., Rows and sides), and each one can also have multiple instances of Speaker (e.g., upper, middle, low, etc.). If we follow the current approach, we would end up with something like: Vehicle.Cabin.Door.Row1.DriverSide.Speaker.Upper.Volume. With the proposed approaches, we could have something nicer and easier to handle like:

  1. Vehicle.Cabin.Door[Row1.DriverSide]Speaker[Upper].Volume
  2. Vehicle.Cabin.Door.Instance[Row1.DriverSide].Speaker.Instance[Upper].Volume

Other examples can be, multiple buttons in a particular component, multiple lights in a particular position inside the cabin, multiple USB ports or button embedded in a seat, etc.

Any opinion or additional suggestion?

erikbosch commented 1 week ago

I see this as a little bit related to #642 and the Left/Right vs DriverSide/PassengerSide discussion. If one see the part in square brackets as an instance labels, then one could possibly allow aliases, so that the two lines below may point to the same physical instance (for a LHD vehicle) 

Vehicle.Cabin.Door[Row1.DriverSide].Window.Position
Vehicle.Cabin.Door[Row1.Left].Window.Position

If we would go this way we need to discuss how this should affect the released artifacts produced by VSS-tool (as can be seen in https://github.com/COVESA/vehicle_signal_specification/releases/tag/v4.2) Today most expand the tree. But if we change approach we should possibly not expand as today, as for example "Row1" should not be a branch itself.

erikbosch commented 1 week ago

MoM: