From 2f9b6263480c0eed5a73c4e0307ad96cd40f8c31 Mon Sep 17 00:00:00 2001 From: Shintaro Tomie <58775300+Shin-kyoto@users.noreply.github.com> Date: Mon, 2 Sep 2024 16:45:40 +0900 Subject: [PATCH] docs(contributing): update the coding guideline (#599) * docs(contributing): update the coding guideline Signed-off-by: Shin-kyoto <58775300+Shin-kyoto@users.noreply.github.com> * docs(contributing): remove hoge Signed-off-by: Shin-kyoto <58775300+Shin-kyoto@users.noreply.github.com> * docs(contributing): update the subtitle Signed-off-by: Shin-kyoto <58775300+Shin-kyoto@users.noreply.github.com> * docs(contributing): Add rationale and sources to the coding guidelines Signed-off-by: Shin-kyoto <58775300+Shin-kyoto@users.noreply.github.com> * docs(contributing): change the example variable's name to understand easily Co-authored-by: Yutaka Kondo * docs(contributing): make the explanation about RCPCPP_* macro appropriate Co-authored-by: Yutaka Kondo * docs(contributing): make the explanation for RCLCPP_* appropriate Signed-off-by: Shin-kyoto <58775300+Shin-kyoto@users.noreply.github.com> * docs(contributing): add the guideline for directory structure of the header files to be exported Signed-off-by: Shin-kyoto <58775300+Shin-kyoto@users.noreply.github.com> * docs(contributing): make the explanation about RCPCPP_* macro appropriate Signed-off-by: Shin-kyoto <58775300+Shin-kyoto@users.noreply.github.com> * docs(contributing): use the appropriate format Signed-off-by: Shin-kyoto <58775300+Shin-kyoto@users.noreply.github.com> * docs(contributing): add Autoware C++ coding guideline as a reference Signed-off-by: Shin-kyoto <58775300+Shin-kyoto@users.noreply.github.com> * docs(contributing): use a specific numbers or reference for better understanding Co-authored-by: Takamasa Horibe * docs(contributing): split guidelines into separate files for each language and removed the content already covered in each language-specific guideline. Signed-off-by: t4-adc * docs(contributing): add reference to autoware style guideline Signed-off-by: Shin-kyoto <58775300+Shin-kyoto@users.noreply.github.com> --------- Signed-off-by: Shin-kyoto <58775300+Shin-kyoto@users.noreply.github.com> Signed-off-by: t4-adc Co-authored-by: Yutaka Kondo Co-authored-by: Takamasa Horibe Co-authored-by: t4-adc --- docs/contributing/coding-guidelines/index.md | 23 +++++++++++++++++++ .../coding-guidelines/languages/cpp.md | 23 +++++++++++++++++++ 2 files changed, 46 insertions(+) diff --git a/docs/contributing/coding-guidelines/index.md b/docs/contributing/coding-guidelines/index.md index 5bb53e4d94b..0b12f7b93a5 100644 --- a/docs/contributing/coding-guidelines/index.md +++ b/docs/contributing/coding-guidelines/index.md @@ -14,6 +14,29 @@ Also, keep in mind the following concepts. - Keep things consistent. - Automate where possible, using simple checks for formatting, syntax, etc. +- Write comments and documentation in English. +- Functions that are too complex (low cohesion) should be appropriately split into smaller functions (e.g. less than 40 lines in one function is recommended in the [google style guideline](https://google.github.io/styleguide/cppguide.html#Write_Short_Functions)). +- Try to minimize the use of member variables or global variables that have a large scope. +- Whenever possible, break large pull requests into smaller, manageable PRs (less than 200 lines of change is recommended in some research e.g. [here](https://opensource.com/article/18/6/anatomy-perfect-pull-request)). - When it comes to code reviews, don't spend too much time on trivial disagreements. For details see: - - +- Please follow the guidelines for each language. + - [C++](./languages/cpp.md) + - [Python](./languages/python.md) + - [Shell script](./languages/shell-scripts.md) + +## Autoware Style Guide + +For Autoware-specific styles, refer to the following: + +- Use the `autoware_` prefix for package names. + - cf. [Directory structure guideline, Package name](./ros-nodes/directory-structure.md#package-name) + - cf. [Prefix packages with autoware\_](https://github.com/orgs/autowarefoundation/discussions/4097) +- Add implementations within the `autoware` namespace. + - cf. [Class design guideline, Namespaces](./ros-nodes/class-design.md#namespaces) + - cf. [Prefix packages with autoware\_, Option 3:](https://github.com/orgs/autowarefoundation/discussions/4097#discussioncomment-8384169) +- The header files to be exported must be placed in the `PACKAGE_NAME/include/autoware/` directory. + - cf. [Directory structure guideline, Exporting headers](./ros-nodes/directory-structure.md#exporting-headers) +- In `CMakeLists.txt`, use `autoware_package()`. + - cf. [autoware_cmake README](https://github.com/autowarefoundation/autoware_cmake/tree/main/autoware_cmake) diff --git a/docs/contributing/coding-guidelines/languages/cpp.md b/docs/contributing/coding-guidelines/languages/cpp.md index ab4d39e4cbf..da9383a377e 100644 --- a/docs/contributing/coding-guidelines/languages/cpp.md +++ b/docs/contributing/coding-guidelines/languages/cpp.md @@ -202,3 +202,26 @@ constexpr double gravity = 9.80665; class RosApi; RosApi ros_api; ``` + +### Do not use the auto keywords with Eigen's expressions (required) + +#### Rationale + +- Avoid using auto with `Eigen::Matrix` or `Eigen::Vector` variables, as it can lead to bugs. + +#### Reference + +- [Eigen, C++11 and the auto keyword](https://eigen.tuxfamily.org/dox/TopicPitfalls.html) + +### Use RCLCPP\_\* (e.g. RCLCPP_INFO) macros instead of printf or std::cout for logging (required) + +#### Rationale + +- Reasons include the following: + - It allows for consistent log level management. For instance, with RCLCPP\_\* macros, you can simply set --log_level to adjust the log level uniformly across the application. + - You can standardize the format using RCUTILS_CONSOLE_OUTPUT_FORMAT. + - With RCLCPP\_\* macros, logs are automatically recorded to /rosout. These logs can be saved to a rosbag, which can then be replayed to review the log data. + +#### Reference + +- [Autoware Documentation for Console logging in ROS Node](../ros-nodes/console-logging.md)