diff --git a/docs/howto/how_to_lint_and_format.md b/docs/howto/how_to_lint_and_format.md deleted file mode 100644 index c31228a0b4c0e9f3a61954fc0d9c2503ee4accbf..0000000000000000000000000000000000000000 --- a/docs/howto/how_to_lint_and_format.md +++ /dev/null @@ -1,38 +0,0 @@ -# How to Lint and Format - -## Coding style - -- **C/C++ coding style**: Apollo adopted the - [Google C++ Style Guide](https://google.github.io/styleguide/cppguide.html). - -## Linters provided in apollo - -Apollo uses the following lint tools to check the code style. **Note:** As for -now, ci will only check the style of C++ codes and it may do so in the future -for codes in other languages. - -| tool | file type | usage (from Apollo root dir) | -| :--------: | :-----------------------------------: | :---------------------------------------------: | -| cpplint | .h .c .hpp .cpp .hh .cc .hxx .cxx .cu | ./apollo.sh lint cpp | -| flake8 | .py | ./apollo.sh lint py | -| shellcheck | .sh .bash .bashrc | ./apollo.sh lint sh | - -To make sure your code conforms to the style guide, you can use command -`bash apollo.sh lint all` to check if your code has any style problems and then -fix them manually. Another option is to use formatters to fix style problems -automatically. - -## Formatters provided in apollo - -Apollo integrated a set of formatting tools that cover many types of files: - -| tool | file type | usage (from Apollo root dir) | configuration file | -| :----------: | :-----------------------------------: | :----------------------------------------------: | :----------------: | -| clang-format | .h .c .hpp .cpp .hh .cc .hxx .cxx .cu | ./apollo.sh format -c | .clang-format | -| autopep8 | .py | ./apollo.sh format -p | tox.ini | -| buildifier | BUILD .BUILD .bzl .bazel | ./apollo.sh format -b | NA | -| shfmt | .sh .bash .bashrc | ./apollo.sh format -s | .editorconfig | -| prettier | .md .json .yaml | ./apollo.sh format -m | .prettier.json | - -For ease of use, you can format all the files with types listed above using -command `./apollo.sh format -a ` diff --git a/docs/specs/formatters_and_linters.md b/docs/specs/formatters_and_linters.md new file mode 100644 index 0000000000000000000000000000000000000000..84b9dfc2881c421620928a553687a5990372695e --- /dev/null +++ b/docs/specs/formatters_and_linters.md @@ -0,0 +1,93 @@ +# Linters and Formatters used in Apollo 6.0 + +``` +Programs should be written for people to read, and +only incidentally for machines to execute. + + -- Harold Abelson +``` + +A great project is made out of consistent code. In the ideal world, you should +not be able to tell who wrote a certain line of the code for the project. Modern +linters and formatters help to close this gap by specifying a simple set of +rules to be enforced on all developers working on the project. Such tools also +stimulate developers to write better code by pointing out common mistakes and +introducing good programming practices. + +Generally, linters are used for catching errors, whereas formatters are used to +fix coding style problems. + +In this article, we will describe briefly the various linters and formatters +used in Apollo. + +## Apollo Coding Style + +As you may already know, Apollo adopted Google coding style for C/C++ and Python +programs. You can refer to +[Google C++ Style Guide](https://google.github.io/styleguide/cppguide.html) and +[Google Python Style Guide](https://google.github.io/styleguide/pyguide.html) +for full text of specifications. + +## Linters in Apollo + +To enforce that everyone conform to Apollo coding style, the following linters +are provided for developers to check style issues. + +**Note:** + +> As the time of this writing, Apollo CI system enforced style check on C++ +> files only. We hope that linters for other languages will be online in the +> near future. + +| Linters | Source Extensions | Apollo Command Used | +| :--------: | :-----------------------------------: | :------------------------- | +| cpplint | .h/.c/.hpp/.cpp/.hh/.cc/.hxx/.cxx/.cu | scripts/apollo_lint.sh cpp | +| flake8 | .py | scripts/apollo_lint.sh py | +| shellcheck | .sh/.bash/.bashrc | scripts/apollo_lint.sh sh | + +To make sure your code conforms to Apollo coding style, you can use +`./apollo.sh lint` to find any possible style problems and fix them manually. + +## Formatters in apollo + +To help ease your life with Apollo coding style, various formatters are +pre-installed into Apollo Docker image, to help you auto-format your code, and +avoid common mistakes when writing code. + +The following table lists the formatters currently integrated into Apollo, +covering C/C++, Python, Bash, Bazel, Markdown, JSON and YAML files. + +| Formatters | Source Extension | Apollo Command Used | Formatter Config | +| :----------: | :------------------------------------: | :----------------------------------------------: | :--------------: | +| clang-format | .h/.c/.hpp/.cpp/.hh/.cc/.hxx/.cxx;/.cu | ./apollo.sh format -c | .clang-format | +| autopep8 | .py | ./apollo.sh format -p | tox.ini | +| buildifier | .BUILD/.bzl/.bazel/WORKSPACE/BUILD | ./apollo.sh format -b | N/A | +| shfmt | .sh/.bash/.bashrc | ./apollo.sh format -s | .editorconfig | +| prettier | .md/.json/.yml | ./apollo.sh format -m | .prettier.json | + +For easy use, you can format all files with types listed above with: + +``` +./apollo.sh format +``` + +For example, + +``` +./apollo.sh format WORKSPACE third_party/BUILD ./scripts/ +``` + +which will auto-format Bazel `WORKSPACE` file under `$APOLLO_ROOT_DIR`, +`third_party/BUILD` file, and all the files under the `./scripts` directory. + +Note: + +> `./apollo.sh format` is expected to work outside Docker if relavant tools +> installed properly. + +## Conclusion + +To summarize, + +- Use `./apollo.sh lint` to check coding style errors. +- Use `./apollo.sh format` to auto-format your code.