Define naming convention for topic and service prefixes

[xmfcx]

Related issue: autowarefoundation/autoware-documentation#292

Topic prefixes

Currently in Autoware we are using prefixes like:

• ~/input/ for topics that the node will subscribe to.
• ~/output/ for topics that the node will publish.
• ~/debug/ for topics that the node will publish for debug purposes.

Should we keep the convention like this?

Some recommendations I've received were like following:

• Make them shorter:
  • ~/in/
  • ~/out/
  • ~/out/debug/
• Use publish/subscribe naming:
  • ~/sub/
  • ~/pub/
  • ~/pub/debug/

Service prefixes

For services, we don't have a convention.

Some existing usages:

• Just use verb like /planning/static_centerline_optimizer/load_map
  • Usage: https://github.com/autowarefoundation/autoware.universe/blob/6992bc5b7083229dc6b02ab4fd961d10a126549d/planning/static_centerline_optimizer/src/static_centerline_optimizer_node.cpp#L194
• Add _srv suffix like ndt_align_srv
  • Usage: https://github.com/autowarefoundation/autoware.universe/blob/6992bc5b7083229dc6b02ab4fd961d10a126549d/localization/ndt_scan_matcher/src/pose_initialization_module.cpp#L40

I think we should consider naming like:

• ~/srv/command_verb
• ~/service/command_verb

How do you think we should go with the naming?
cc. @mitsudome-r @kenji-miyake @isamu-takagi

[xmfcx]

I personally prefer shorter style:

• ~/sub/topic_name
• ~/pub/topic_name
• ~/pub/debug/topic_name
• ~/srv/command_verb

And pub, sub, srv makes it clear that they are publisher, subscriber and service.

[kenji-miyake]

@xmfcx Thank you for creating this thread! I agree with you two.

~/sub/topic_name
~/pub/topic_name
~/pub/debug/topic_name
~/cli/service_name(command_verb)
~/srv/service_name(command_verb)
~/srv/debug/service_name(command_verb) # Might be used Sometimes?

[kenji-miyake]

One concern I have is that what srv stands for is ambiguous, service or server.
Considering the existence of cli, is it server?

[mitsudome-r]

@xmfcx @kenji-miyake I also agree with your proposal.

[yukkysaito]

@xmfcx @kenji-miyake I agree with you, too

[xmfcx]

One concern I have is that what srv stands for is ambiguous, service or server.
Considering the existence of cli, is it server?

I think this is not a big issue, even ros2 uses service and server almost interchangeably:

• https://docs.ros2.org/latest/api/rclcpp/

• - Service Client
    - rclcpp::Node::create_client()
    - rclcpp::Client
    - rclcpp/client.hpp
  - Service Server
    - rclcpp::Node::create_service()
    - rclcpp::Service
    - rclcpp/service.hpp
  

• There is create_client and create_service (not create_server).

[kenji-miyake]

Related to this topic, what do you think about the naming convention of interfaces in launch args?
I personally prefer slash because it's easy to copy-and-paste and edit. I mean, it's annoying to replace / with _.

• Use underscore:

    <arg name="sub_foo" default="/path/to/foo"/>
    <arg name="pub_bar" default="/path/to/bar"/>
    <arg name="cli_baz" default="/path/to/baz"/>
    <arg name="srv_qux" default="/path/to/qux"/>
  
    <node ...>
      <remap from="~/sub/foo" to="$(var sub_foo)"/>
      <remap from="~/pub/bar" to="$(var pub_bar)"/>
      <remap from="~/cli/baz" to="$(var cli_baz)"/>
      <remap from="~/srv/qux" to="$(var srv_qux)"/>
    </node>

• Use slash:

    <arg name="sub/foo" default="/path/to/foo"/>
    <arg name="pub/bar" default="/path/to/bar"/>
    <arg name="cli/baz" default="/path/to/baz"/>
    <arg name="srv/qux" default="/path/to/qux"/>
  
    <node ...>
      <remap from="~/sub/foo" to="$(var sub/foo)"/>
      <remap from="~/pub/bar" to="$(var pub/bar)"/>
      <remap from="~/cli/baz" to="$(var cli/baz)"/>
      <remap from="~/srv/qux" to="$(var srv/qux)"/>
    </node>

• Others: (Please propose your ideas!)

[xmfcx]

I prefer slash too.

[kenji-miyake]

Also, I think we need to define rules for feature flags.

• Whether to add any prefix (such as flag).

  <arg name="enable_foo_feature" default="true"/>
  
  <arg name="flag/enable_foo_feature" default="true"/>

• Which prefix name to use.

  • enable_
  • use_
  • etc.

[xmfcx]

<arg name="enable/foo_feature" default="true"/>

Do you think we could use it like this?

[kenji-miyake]

Yes, I think it's possible.
But I personally prefer nouns for the category, for example feature_flag or something like that might be good.
Actually, anything is okay if it's defined in the guidelines.

[kenji-miyake]

However, considering https://github.com/orgs/autowarefoundation/discussions/3171#discussioncomment-4615840, I'm not sure what will use these types of args.
So, maybe revisiting this after rough cleaning up would be better?

[xmfcx]

@kenji-miyake these feature flags can be in the param files.

Looking at https://docs.ros.org/en/foxy/How-To-Guides/Parameters-YAML-files-migration-guide.html#yaml-file-example

enable_feature:
  foo: true

Something like this can be recommended.

[kenji-miyake]

I see. In that case, it's a good idea to define the convention for such parameters!

[kenji-miyake]

Also, rules for parameters?
I personally think writing as many parameters in .param.yaml as possible is good to keep a consistent style.

• No prefix.

  <arg name="foo_threshold" default="1.0"/>

• Use some prefix such as param.

  <arg name="param/foo_threshold" default="1.0"/>

• Forbid arg and define all parameters in .param.yaml file. The parameters that must be written in launch files are allowed.

• Others.

[yukkysaito]

LGTM 👍

[xmfcx]

I'd go for

Forbid arg and define all parameters in .param.yaml file. The parameters that must be written in launch files are allowed.

Because launch parameter overriding makes things way too complicated as we use more launch files inside others.

Maybe only allow for topic name remapping?

[cyn-liu]

I'd go for

Forbid arg and define all parameters in .param.yaml file. The parameters that must be written in launch files are allowed.

Because launch parameter overriding makes things way too complicated as we use more launch files inside others.

Maybe only allow for topic name remapping?

I agree with this proposal , define the remapping related parameters in the lunch file, and other parameters can be defined in the param.yaml file.