docs(contributing): update the coding guideline

[Shin-kyoto]

Description

Updated the coding guideline.

To the reviewers:

• Please check whether there are any inappropriate guidelines included.
• In particular, verify if my thoughts on new/delete/free/raw pointers and throw are correct.
• If there are any other points that should be mentioned, please let me know. I'd like to add anything that can be easily incorporated.
• Please confirm if the structure of the text, the subtitles, and the paragraph divisions are appropriate.
• Regarding the ROS nodes guidelines in the ROS 2 Style Guide, I'm not sure where the link should point to, so I've linked it to class-design.md. If there is a better option, please let me know.
• Since I think that the coding guideline document is still incomplete, I have left the "Under Construction" note. Please let me know if it should be removed.

Pre-review checklist for the PR author

The PR author must check the checkboxes below when creating the PR.

• I've confirmed the contribution guidelines.
• The PR follows the pull request guidelines.

In-review checklist for the PR reviewers

The Reviewers must check the checkboxes below before approval.

• The PR follows the pull request guidelines.

Post-review checklist for the PR author

The PR author must check the checkboxes below before merging.

• There are no open discussions or they are tracked via tickets.

After all checkboxes are checked, anyone who has write access can merge the PR.

[github-actions]

Documentation URL: https://autowarefoundation.github.io/autoware-documentation/pr-599/
Modified URLs:

• https://autowarefoundation.github.io/autoware-documentation/pr-599/contributing/coding-guidelines/
• https://autowarefoundation.github.io/autoware-documentation/pr-599/contributing/coding-guidelines/languages/cpp/

[Shin-kyoto]

@xmfcx @YossyTaka @ytakano
Please add the comments if you have any idea about the coding guideline 🙏

[youtalk]

Thank you for your updates.

[sasakisasaki]

I have read all contents in the index.md and understood this is informative notes. Thank you so much!

[mitsudome-r]

The guideline itself generally looks okay, but most of them seem to be duplicate of the materials in other pages like:

• https://autowarefoundation.github.io/autoware-documentation/main/contributing/coding-guidelines/languages/cpp/
• https://autowarefoundation.github.io/autoware-documentation/main/contributing/coding-guidelines/ros-nodes/directory-structure/
• https://autowarefoundation.github.io/autoware-documentation/main/contributing/coding-guidelines/ros-nodes/parameters/

Could you explain the purpose of this change. Is your intention to add a summary page that require particular attention?

In that case, I'm okay to add Autoware specific guidelines mentioned in this summary page(like adding autoware_ prefix to package names), but I rather keep the details about C++ guidelines as a separate page and just put a link to that page. It would make us harder to keep consistency within our documentation if there are duplicate materials explained in different places.

[Shin-kyoto]

The guideline itself generally looks okay, but most of them seem to be duplicate of the materials in other pages like:

• https://autowarefoundation.github.io/autoware-documentation/main/contributing/coding-guidelines/languages/cpp/
• https://autowarefoundation.github.io/autoware-documentation/main/contributing/coding-guidelines/ros-nodes/directory-structure/
• https://autowarefoundation.github.io/autoware-documentation/main/contributing/coding-guidelines/ros-nodes/parameters/

Could you explain the purpose of this change. Is your intention to add a summary page that require particular attention?

In that case, I'm okay to add Autoware specific guidelines mentioned in this summary page(like adding autoware_ prefix to package names), but I rather keep the details about C++ guidelines as a separate page and just put a link to that page. It would make us harder to keep consistency within our documentation if there are duplicate materials explained in different places.

Thank you for your good comment!!
I’m considering making changes based on the following approach. What do you think about it? @mitsudome-r

• Move the content related to C++ and ROS to the separated pages.
• Document Autoware-specific guidelines on this page.

[TakaHoribe]

@Shin-kyoto Thank you for your work. Establishing coding guidelines is a great activity as it clarifies the criteria for PRs and reduces review time.

As @mitsudome-r mentioned, the document contains information with different levels of detail and some overlap. For example, the using .at(i) instead of [i], and the using the autoware_ prefix in packages are very different in scope.

It would be helpful to explain why each item is included on this page clearly. For instance, essential points like using the autoware_ prefix should be clearly stated. On the other hand, for more specific details (like index access or logger usage), it might be better to phrase it as, “Here are some frequent issues raised in reviews or static analysis, referenced from the C++/ROS guidelines".

[Shin-kyoto]

As @mitsudome-r mentioned, the document contains information with different levels of detail and some overlap. For example, the using .at(i) instead of [i], and the using the autoware_ prefix in packages are very different in scope.

It would be helpful to explain why each item is included on this page clearly. For instance, essential points like using the autoware_ prefix should be clearly stated. On the other hand, for more specific details (like index access or logger usage), it might be better to phrase it as, “Here are some frequent issues raised in reviews or static analysis, referenced from the C++/ROS guidelines".

Thanks!! 👍
I will update document following @mitsudome-r after his answer to #599 (comment)

[mitsudome-r]

@Shin-kyoto Thanks!

Move the content related to C++ and ROS to the separated pages.
Document Autoware-specific guidelines on this page.

I think this approach sounds reasonable to me.

[Shin-kyoto]

The guideline itself generally looks okay, but most of them seem to be duplicate of the materials in other pages like:

• https://autowarefoundation.github.io/autoware-documentation/main/contributing/coding-guidelines/languages/cpp/
• https://autowarefoundation.github.io/autoware-documentation/main/contributing/coding-guidelines/ros-nodes/directory-structure/
• https://autowarefoundation.github.io/autoware-documentation/main/contributing/coding-guidelines/ros-nodes/parameters/

Could you explain the purpose of this change. Is your intention to add a summary page that require particular attention?

In that case, I'm okay to add Autoware specific guidelines mentioned in this summary page(like adding autoware_ prefix to package names), but I rather keep the details about C++ guidelines as a separate page and just put a link to that page. It would make us harder to keep consistency within our documentation if there are duplicate materials explained in different places.

@mitsudome-r @TakaHoribe @isamu-takagi
I changed in 289937d

[Shin-kyoto]

@mitsudome-r @TakaHoribe
Can you review this PR, again?

[mitsudome-r]

I've made a small suggestions about the reference link. Otherwise, the PR looks good to me.

[TakaHoribe]

LGTM, thank you for your work!

[Shin-kyoto]

Thank you for your review!!
Contribution guideline is very important and it is necessary to review it strictly. Now, I confirmed that

• I got the LGTMs from five awf members
• I got the LGTM from maintainer @mitsudome-r

So, I will squash and merge it.