代码风格和语言版本 [1415]
目录 []
为了实现外观一致的产品，我们将遵循各语言的外部（如果可能）定义的样式指南。对于包布局或文档布局等其他事项，我们将需要制定自己的指南，借鉴当前流行的样式。 [1416]
此外，开发人员应尽可能使用集成工具来检查编辑器中是否遵循了这些指南。例如，每个人都应该在其编辑器中内置一个 PEP8 检查器，以减少与样式相关的审查迭代。 [1417]
此外，尽可能地，软件包应在其单元测试中检查样式，以帮助自动检测样式问题（参见 ament_lint_auto）。 [1418]
C [1419]
C++ [1436]
样式 [1422]
我们将使用 Google C++ Style Guide，并进行一些修改： [1438]
函数和方法命名 [1450]
花括号的风格选择 [1502]
对于
function、class、enum和struct的定义，使用空格后的开放花括号，但是对于if、else、while、for等语句使用相邻的花括号... [1503]例外情况：当
if``（或 ``while等）条件太长需要换行时，使用开放花括号（即不相邻的形式）。 [1504]
当函数调用不能在一行内容纳时，在开放的括号处换行（不在参数之间），并在下一行以2个空格缩进开始。对于更多的参数，继续使用2个空格缩进的格式进行下一行。注意，这一点在 Google 风格指南 上有内部矛盾。 [1505]
对于太长无法放在一行的``if``（以及``while``等）条件同样适用。 [1506]
示例 [1507]
这是可以的： [1508]
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);
这是**不**可以的： [1509]
int main(int argc, char **argv) {
return 0;
}
if (this &&
that ||
both) {
...
}
使用大括号而不是过多的缩进，例如用于区分构造函数中的代码和构造函数初始化列表 [1510]
这是可以的： [1508]
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();
...
}
这是 不正确的，甚至很奇怪（Google 的方式？）： [1511]
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();
...
}
代码检查工具 [16100]
我们使用 Google 的 cpplint.py 和 uncrustify 的组合来检查这些风格。 [1513]
我们提供带有自定义配置的命令行工具： [1514]
一些格式化工具，例如ament_uncrustify和ament_clang_format，支持“--reformat”选项以直接应用更改。 [1518]
我们还运行其他工具来尽可能检测和消除警告。以下是我们在所有软件包上尝试做的一些额外工作的非详尽列表： [1519]
使用编译器标志，如“-Wall -Wextra -Wpedantic”。 [1520]
运行静态代码分析工具，例如cppcheck，我们已将其集成到`ament_cppcheck <https://github.com/ament/ament_lint/blob/humble/ament_cppcheck/doc/index.rst>`__中。 [1521]
Python [1522]
Markdown / reStructured Text / docblocks [1548]
样式 [1422]
以下用于格式化文本的规则旨在提高可读性和版本控制。 [1549]
[.md, .rst only] 每个章节标题前应有一个空行，后面也应有一个空行。 [1550]
原因：这有助于在浏览文档时快速获取结构概览。 [1551]
[.rst only] 在 reStructured Text 中，标题应遵循 Sphinx 风格指南 中描述的层次结构： [1552]
[仅限.md格式] 在Markdown中，标题应遵循`Markdown语法文档<https://daringfireball.net/projects/markdown/syntax#header>`__中描述的ATX样式 [1560]
ATX样式的标题使用1-6个井号字符（
#）在行首表示标题级别1-6 [1561]应在井号和标题之间使用一个空格（例如
# 标题1）以便更容易进行视觉分隔 [1562]ATX样式的偏好来自于`Google Markdown样式指南<https://github.com/google/styleguide/blob/gh-pages/docguide/style.md#atx-style-headings>`__ [1563]
原理: ATX 样式的标题更容易搜索和维护，并且使得前两个标题级别与其他级别保持一致。 [1564]
[任意] 每个句子必须从新的一行开始。 [1565]
原理: 对于较长的段落，一开始的单个更改会导致差异难以阅读，因为它会一直延续到整个段落。 [1566]
[任意] 每个句子可以选择性地换行，以保持每行短小。 [1567]
[任意] 行末不应有任何空白。 [1568]
[仅限 .md、.rst] 代码块前后必须有空行。 [1569]
原因：只有在有围栏代码块的直接前后空格才有意义。遵循这些指示将确保高亮显示正常且一致。 [1570]
[仅限 .md、.rst] 代码块应指定语法（例如
bash）。 [1571]