From d2c6031c85b3eee84137ed11cd6e1e8a85234180 Mon Sep 17 00:00:00 2001 From: storypku Date: Mon, 7 Sep 2020 22:51:14 +0800 Subject: [PATCH] Docs: update "Apollo Best Coding Practice" --- CONTRIBUTING.md | 4 +- docs/technical_tutorial/README.md | 2 +- ...tice.md => apollo_best_coding_practice.md} | 72 +++++++++++++++---- 3 files changed, 61 insertions(+), 17 deletions(-) rename docs/technical_tutorial/{best_coding_practice.md => apollo_best_coding_practice.md} (53%) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a42f738595f..5f7a5668f2c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -38,12 +38,10 @@ You can use command `bash apollo.sh test` to run all unit tests. * **Python coding style**: Apollo adopted the [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html). You can use the [yapf](https://github.com/google/yapf) command `yapf -i --style='{based_on_style: google}' foo.py` to format a file foo.py. -* **Apollo best coding practice**: Please also refer to [Apollo Best Coding Practice](docs/technical_tutorial/best_coding_practice.md) for more coding practice disciplines. +* **Apollo best coding practice**: Please also refer to [Apollo Best Coding Practice](docs/technical_tutorial/apollo_best_coding_practice.md) for more coding practice disciplines. * **BUILD coding style** : you can use command `bash apollo.sh buildify` to format your BUILD files before you submit. -* **Best coding practice**: Follow [this guide](docs/technical_tutorial/best_coding_practice.md) - #### Documentation If your code is not straightforward for other contributors to understand, it is recommended to implement the code in a clear and efficient way, and provide sufficient comments and documentation. diff --git a/docs/technical_tutorial/README.md b/docs/technical_tutorial/README.md index c3a35c0c765..52edcc1a903 100644 --- a/docs/technical_tutorial/README.md +++ b/docs/technical_tutorial/README.md @@ -9,4 +9,4 @@ Refer these documents as a guide to all other relevant documents for the version - [Apollo 3.0 cn](apollo_3.0_technical_tutorial_cn.md) - [Apollo 2.5](apollo_2.5_technical_tutorial.md) - [Navigation mode cn](navigation_mode_tutorial_cn.md) -- [Best Coding Practice](best_coding_practice.md) \ No newline at end of file +- [Apollo Best Coding Practice](apollo_best_coding_practice.md) diff --git a/docs/technical_tutorial/best_coding_practice.md b/docs/technical_tutorial/apollo_best_coding_practice.md similarity index 53% rename from docs/technical_tutorial/best_coding_practice.md rename to docs/technical_tutorial/apollo_best_coding_practice.md index 0a63f77f114..4cf56a92815 100644 --- a/docs/technical_tutorial/best_coding_practice.md +++ b/docs/technical_tutorial/apollo_best_coding_practice.md @@ -1,12 +1,12 @@ -# Best Coding Practice +# Apollo Best Coding Practice -1. Always compile all, test all and lint all. +1. Always build, test, and lint all. ```bash - apollo.sh check + ./apollo.sh check ``` -1. Always write unit test and put it along with the source code. +1. Always write unit tests and put them along with the source files. ```text foobar.h @@ -14,9 +14,9 @@ foobar_test.cc ``` -1. A bazel target contains at most one header and one source file. +1. A bazel target should contain at most one header and one source file. - ```text + ```python cc_library( name = "foobar", hdrs = ["foobar.h"], @@ -36,12 +36,13 @@ ) ``` - You could setup and run `scripts/buildifier.sh ` to fix BUILD file - style issues. + You can use `scripts/buildifier.sh ` to fix BUILD file style + issues. -1. In general, we follow +1. In general, Apollo follows [Google C++ coding style](https://google.github.io/styleguide/cppguide.html). - You could run `scripts/clang-format.sh ` to fix C++ style issues. + You should run `scripts/clang_format.sh ` to fix + C++ style issues. 1. Simple and unified function signature. @@ -71,14 +72,59 @@ const std::string& name() const; ``` -1. The DRY principle. +1. Prefer C++ headers over C headers. + + We prefer using `#include ` over `#include `, `` over + ``, `` over ``, `` over ``, etc. + +1. Include necessary headers **only**. No more, no less. + + Please also pay attention to header orders. Again, you can use + `scripts/clang_format.sh` to fix header order issues. + +1. List only direct dependencies in `deps` section of a Bazel target. + + Generally, only targets to which the included headers belongs should be + listed as a dependency. + + For example, suppose `sandwich.h` includes `bread.h` which in turn includes + `flour.h`. Since `sandwich.h` doesn't include `flour.h` directly (who wants + flour in their sandwich?), the BUILD file would look like this: + + ```python + cc_library( + name = "sandwich", + srcs = ["sandwich.cc"], + hdrs = ["sandwich.h"], + deps = [ + ":bread", + # BAD practice to uncomment the line below + # ":flour", + ], + ) + + cc_library( + name = "bread", + srcs = ["bread.cc"], + hdrs = ["bread.h"], + deps = [":flour"], + ) + + cc_library( + name = "flour", + srcs = ["flour.cc"], + hdrs = ["flour.h"], + ) + ``` + +1. Conform to the DRY principle. Don't repeat yourself, in any way. Avoid duplicate classes, functions, const variables, or a simple piece of code. Some examples: - It's fine to refer a name with full path once, like - `apollo::common::util::Type`, but better to make a short alias - if you need to use twice or more: `using apollo::common::util::Type;`. + `apollo::common::util::Type`, but better to make a short alias if you need + to use twice or more: `using apollo::common::util::Type;`. - It's fine to access a sub-field of proto once in cascade style, like `a_proto.field_1().field_2().field_3()`, but better to save the reference of a common part first if you need to access it twice or more: