RFC 69：C/C++代码格式

本文提出并描述了GDAL中跨C和C++源代码所需的代码格式化风格。

作者：

库尔特·施韦尔

联系方式：

schwehr@google.com/schwehr@gmail.com

起动：

2017年5月4日

状态：

Work-In-Progress

此RFC基于 GEOS RFC 4 作者：MateuszŁoskot。

TODO： 给出格式示例。

总结

该文档提出并描述了在C语言和C++语言中GDAL编程所需的默认代码格式化准则。

本文档的目标是启动流程以达成默认代码格式样式的协议。

动机

需要决定GDAL源代码的格式，并将这种全局一致的格式应用到GDAL C/C++代码库。

一种统一的、代码库范围的格式样式使阅读和理解现有代码变得更容易，编写的代码专注于新开发的重要方面并且更令人愉快，在补丁或请求代码检查期间消除了负担，并防止了 bikeshedding religious arguments . 即使在小项目中，有贡献的开发人员也会发现在没有商定的代码格式的情况下工作的问题。

许多开源软件项目已经证明了这些指导原则的实用性。

建议的范围特别限于格式化样式准则。这并不是要开发一个通用的编码指南，涵盖编写软件的其他方面，如命名等。

提案

对于开发人员来说，轻松地生成格式正确的代码是很重要的。

建议使用 clang-format 版本3.8或更高版本定义GDAL代码的C++代码格式化规则。

这个 clang-format 是一种自动格式C/C++代码的工具，这样开发者就不用担心风格问题了。与其他使用自己的解析器的工具不同， clang-format 使用CLAN TKEngisher，并支持与CLAN编译器相同的C++源代码。这保证了正确的输出并提供了独特的特性（例如，不管是代码、字符串还是数组，都会换行——这是AStyle无法做到的）。

样式设置可以在 .clang-format 不过，为了使配置文件尽可能简单，我们将使用默认样式（LLVM样式？）。

The clang-format is straightforward to run and can support development workflow as standalone tool or as one of many editor integrations or other bespoke utilities (eg. git cl format [Chromium]).

不建议代码重新格式化的自动化。这将是治标不治本：开发人员没有遵循代码格式化标准。

尽管没有提出强制使用默认格式样式的方法，但当前使用的CI服务（例如Travis CI）可以用作提交后安全阀-将clang format lint failure用作编译中断（例如。 clang_format.py MongoDB使用的生成脚本）。或者，可以在SVN/Git中安装一个网关守卫，拒绝代码不符合代码格式样式的提交。

代码格式规则

要使用什么代码格式规则？

“一个成熟的工程师知道一个标准比哪个标准更重要。” ~ [MongoDB]

clang-format 提供了几个默认值（如LLVM、Mozilla、Linux、谷歌C++风格）。

建议使用其中一种基本样式而不做任何修改。可以对配置进行微调，但是这个RFC的目标是简单。

原因有两个：

  • 使GDAL代码与已建立的C/C++项目的广谱一致

  • 长期争论和宗教战争的预防。

.clang-format

希望避免在代码库中需要.clang格式的文件。

.editorconfig

EditorConfig 目前正在使用 .editorconfig 提供文件是为了自动告诉流行的代码编辑器一些基本的样式设置，如缩进、空白和可分辨类型的纯文本文件的行尾标记。

这个 .editorconfig 必须更新文件以匹配选定的 .clang-format 设置（如果需要）。

EOL

clang-format 不强制行尾。

下线标记被认为是 a part of a file encoding decision 而不是任何编码风格的一部分。

下线标记可以作为项目范围内的设置来实施，并由 .gitattributes 和 .editorconfig .

但是，在开发者选择的环境中，它仍应保留为可配置的设置（例如。 git config )独立于项目范围的设置。

大改版

如何处理现有代码？

建议只对代码库进行一次大的重新格式化。

虽然它可能会在存储库日志中造成混乱（例如。 svn blame )，如果它不经常发生（例如每年一次），并且在那时应用于整个代码库，那么它不应该对源代码历史造成很大的破坏。处理扭曲历史的一种方法是 git blame -w 在比较提交时忽略空白。

部分应用代码格式化规则将创建更多的工作，而不会带来全部好处 [MongoDB] 导致不同风格的代码库混合。

分支机构

要在其中运行大改型的分支是：

  • trunk

  • [STRIKEOUT:branches/2.2]

  • [STRIKEOUT:branches/2.1]

  • [STRIKEOUT:branches/2.0]

大改革后

如何对抗代码库中的自然熵：

  • 强烈建议使用 clang-format 编写代码时进行集成。

  • 提交或打开拉取请求之前更改了代码的格式。

  • 如果必须提交代码格式的更改，请在单独的提交中进行。避免使用代码和格式更改的混合提交。

    • 存储库中存在历史混乱的缺点，但这个建议指出，具有不同样式的代码库更糟糕。

毕竟，在代码格式化或代码讨论上浪费的每一分钟都会被消除 ~ [MongoDB]

实施

设置Travis CI“样式安全阀”，根据 ​clang_format.py MongoDB编写的脚本。

其他

使用GCC6+构建GDAL的人可能会喜欢一致的代码格式样式，因为它将有助于避免 new compiler warnings ：

src/geom/Polygon.cpp: In member function ‘virtual int geos::geom::Polygon::getCoordinateDimension() const’:
src/geom/Polygon.cpp:154:5: warning: this ‘if’ clause does not guard... [-Wmisleading-indentation]
     if( shell != NULL )
     ^~
src/geom/Polygon.cpp:157:2: note: ...this statement, but the latter is misleadingly indented as if it is guarded by the ‘if’
  size_t nholes=holes->size();
  ^~~~~~

工具书类