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 <yutaka.kondo@youtalk.jp> * docs(contributing): make the explanation about RCPCPP_* macro appropriate Co-authored-by: Yutaka Kondo <yutaka.kondo@youtalk.jp> * 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 <horibe.takamasa@gmail.com> * 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 <grp-rd-1-adc-admin@tier4.jp> * 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 <grp-rd-1-adc-admin@tier4.jp> Co-authored-by: Yutaka Kondo <yutaka.kondo@youtalk.jp> Co-authored-by: Takamasa Horibe <horibe.takamasa@gmail.com> Co-authored-by: t4-adc <grp-rd-1-adc-admin@tier4.jp>
autowarefoundation · Sep 2, 2024 · 2f9b626 · 2f9b626
1 parent 9a1c6e9
commit 2f9b626
Show file tree

Hide file tree

Showing 2 changed files with 46 additions and 0 deletions.
diff --git 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:
   - <https://en.wikipedia.org/wiki/Law_of_triviality>
   - <https://steemit.com/programming/@emrebeyler/code-reviews-and-parkinson-s-law-of-triviality>
+- 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
@@ -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)