代码样式和语言版本 [待校准@231]
目录
为了获得外观一致的产品，我们都将遵循每种语言的外部 (如果可能) 定义的风格指南。对于其他事情，如包布局或文档布局，我们需要提出我们自己的指导方针，借鉴现在使用的当前流行风格。 [待校准@232]
此外，在可能的情况下，开发人员应使用集成工具来允许他们检查编辑器中是否遵循了这些准则。例如，每个人都应该在其编辑器中内置一个PEP8检查器，以减少与样式相关的审核迭代。 [待校准@233]
此外，在可能的情况下，包应检查样式，作为其单元测试的一部分，以帮助自动检测样式问题 (见 ament_lint_auto )。 [待校准@234]
C [待校准@235]
风格 [待校准@238]
我们将使用 Python's PEP7 作为我们的C风格指南，并进行一些修改和补充: [待校准@239]
我们将以C99为目标，因为我们不需要支持C89 (正如PEP7所建议的那样) [待校准@240]
C + + 风格的
//评论是允许的 [待校准@243]始终将文字放在比较运算符的左侧，例如
0 == ret而不是ret == 0[待校准@244]基本原理:
ret == 0太容易意外变成ret = 0[待校准@245]
以下所有修改仅在我们不编写Python模块时适用: [待校准@246]
我们可以使用 pep7 python模块进行样式检查。编辑器集成似乎很小，我们可能需要更详细地研究C的自动检查。 [待校准@250]
C++ [待校准@251]
风格 [待校准@238]
我们将使用 Google C++ Style Guide ，并做一些修改: [待校准@253]
函数和方法命名 [待校准@265]
指针语法对齐 [待校准@303]
使用 “碳 * c; `` instead of `` 碳 * c; `` or `` 碳 * c; `` because of this scenario `` 碳 * c，* d，* e;” [待校准@304]
项目完结，系统自动填充内容 [待校准@317]
使用左大括号的
function，class，struct定义，但拥抱撑if，else，while，for等 .. [待校准@318]例外: 当
if(或while等) 条件足够长，需要换行时，使用开放式支架 (即，不要拥抱)。 [待校准@319]
当函数调用不能适合一行时，用打开的圆括号 (不在参数之间) 换行，并在下一行用2个空格缩进开始它们。继续在后续行上使用2空格缩进，以获取更多参数。(注意 Google style guide 在这一点上是内部矛盾的。) [待校准@320]
[需手动修复的语法]
if(和while等) 条件也是如此，它们太长而不能放在一条线上。 [待校准@321]
示例 [待校准@322]
可以: [待校准@323]
int main(int argc, char **argv)
{
if (condition) {
return 0;
} else {
return 1;
}
}
if (this && that || both) {
...
}
// Long condition; open brace
if (
this && that || both && this && that || both && this && that || both && this && that)
{
...
}
// Short function call
call_func(foo, bar);
// Long function call; wrap at the open parenthesis
call_func(
foo, bar, foo, bar, foo, bar, foo, bar, foo, bar, foo, bar, foo, bar, foo, bar, foo, bar,
foo, bar, foo, bar, foo, bar, foo, bar, foo, bar, foo, bar, foo, bar, foo, bar, foo, bar);
// Very long function argument; separate it for readability
call_func(
bang,
fooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo,
bar, bat);
这不是好: [待校准@324]
int main(int argc, char **argv) {
return 0;
}
if (this &&
that ||
both) {
...
}
使用打开的大括号而不是过多的缩进，例如，用于区分构造函数代码和构造函数初始化程序列表 [待校准@325]
可以: [待校准@323]
ReturnType LongClassName::ReallyReallyReallyLongFunctionName(
Type par_name1, // 2 space indent
Type par_name2,
Type par_name3)
{
DoSomething(); // 2 space indent
...
}
MyClass::MyClass(int var)
: some_var_(var),
some_other_var_(var + 1)
{
...
DoSomething();
...
}
这不好，甚至很奇怪 (谷歌的方式？): [待校准@326]
ReturnType LongClassName::ReallyReallyReallyLongFunctionName(
Type par_name1, // 4 space indent
Type par_name2,
Type par_name3) {
DoSomething(); // 2 space indent
...
}
MyClass::MyClass(int var)
: some_var_(var), // 4 space indent
some_other_var_(var + 1) { // lined up
...
DoSomething();
...
}
林特 [待校准@327]
我们结合谷歌的 cpplint.py and uncrustify 检查这些风格。 [待校准@328]
我们提供具有自定义配置的命令行工具: [待校准@329]
我们还运行其他工具来检测和消除尽可能多的警告。以下是我们在所有包中尝试做的其他事情的非详尽列表: [待校准@332]
使用编译器标志，如
-Wall -Wextra -Wpedantic[待校准@333]像
cppcheck一样运行静态代码分析，我们已经将其集成到 ament_cppcheck 中。 [待校准@334]
蟒蛇 [待校准@335]
风格 [待校准@238]
我们将使用 PEP8 guidelines 作为代码格式。 [待校准@338]
我们选择了以下更精确的规则，其中PEP 8留下了一些自由: [待校准@339]
在单元测试和/或编辑器集成中，应该使用像 (ament_)pycodestyle Python包这样的工具来检查Python代码样式。 [待校准@343]
linter中使用的pycodestyle配置是 here 。 [待校准@344]
与编辑器集成: [待校准@345]
原子: https://atom.io/包/linter-pycodestyle [待校准@346]
emacs: https://www.emacswiki.org/emacs/PythonProgrammingInEmacs [待校准@347]
Sublime Text: https://sublime.wbond.net/包/SublimeLinter-flake8 [待校准@348]
vim: https://github.com/nvie/ vim-flake8 [待校准@349]
降价/重组文本/文档块 [待校准@361]
风格 [待校准@238]
以下格式化文本的规则旨在提高可读性和版本控制。 [待校准@362]
[.md, .rst only] Each section title should be preceded by one empty line and succeeded by one empty line.
基本原理: 在筛选文件时，它加快了对结构的概述。 [待校准@364]
[.rst only] In reStructured Text the headings should follow the hierarchy described in the Sphinx style guide:
[.md only] In Markdown the headings should follow the ATX-style described in the Markdown syntax documentation
ATX样式的标头在行首使用1-6个哈希字符 (“#”) 表示标头级别1-6。 [待校准@374]
应该在散列和标题标题之间使用一个空格 (例如 “# 标题1”)，以便更容易在视觉上分离它们。 [待校准@375]
ATX风格偏好的理由来自 Google Markdown style guide [待校准@376]
基本原理: ATX风格的标题更易于搜索和维护，并使前两个标题级别与其他级别一致。 [待校准@377]
[any] Each sentence must start on a new line.
基本原理: 对于较长的段落，开头的单个更改会使差异不可读，因为它会延续到整个段落。 [待校准@379]
[any] Each sentence can optionally be wrapped to keep each line short.
[any] The lines should not have any trailing white spaces.
[.md, .rst only] A code block must be preceded and succeeded by an empty line.
基本原理: 空格仅在围栏代码块之前和之后直接有效。追踪这些说明将确保突出显示工作正常且一致。 [待校准@383]
[.md, .rst only] A code block should specify a syntax (e.g.
bash).