Docs: update "Apollo Best Coding Practice"

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.

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)
+- [Apollo Best Coding Practice](apollo_best_coding_practice.md)

docs/technical_tutorial/best_coding_practice.md → docs/technical_tutorial/apollo_best_coding_practice.md

@@ -1,22 +1,22 @@
-# 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
    foobar.cc
    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 <some/path>` to fix BUILD file
-   style issues.
+   You can use `scripts/buildifier.sh <path/to/BUILD>` 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 <some/path>` to fix C++ style issues.
+   You should run `scripts/clang_format.sh <path/to/cpp/dirs/or/files>` 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 <ctime>` over `#include <time.h>`, `<cmath>` over
+   `<math.h>`, `<cstdio>` over `<stdio.h>`, `<cstring>` over `<string.h>`, 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: