[geos-devel] RFC 4: Code Formatting Style

[Mateusz Loskot]

On 23 March 2017 at 18:42, Sandro Santilli <strk at kbt.io> wrote:
> On Thu, Mar 23, 2017 at 06:25:05PM +0100, Mateusz Loskot wrote:
>
>> For your delectation, RFC4 <http://trac.osgeo.org/geos/wiki/RFC4>
>
> Thanks for the time you put into this Mateusz.
> I like the idea of *enforcing* a style, but I'm of course concerned
> about being able to deal with this in the future, and about history
> destruction (git blame, as you call it).
>
> About the first concern (deal with it):
>
> We found out with PostGIS that changes in the formatting tool (astyle,
> in that case) made it hard for developers to enforce a given style (ie:
> different versions of the tool behaved differently).

I don't have any arguments-from-experience up my sleeve against AStyle,
but I have heard lots of such stories. Major advantage of clang-format
is the fact it is based on core of clang compiler.
An observation, biased or not, about large projects
(eg. Chromium, CMake, KDE, MongoDB, Apache Mesos)
switch to clang-format is an important indicator.

> On Debian stable (8.0) I find 3 distinct versions packaged (3.8,
> which you reference, from backports):
>
>   clang-format-3.4 - Tool to format C/C++/Obj-C code
>   clang-format-3.5 - Tool to format C/C++/Obj-C code
>   clang-format-3.8 - Tool to format C/C++/Obj-C code
>
> On Ubuntu LTS (16.04) I have 4 (or 5):
>
>   clang-format - Tool to format C/C++/Obj-C code
>   clang-format-3.5 - Tool to format C/C++/Obj-C code
>   clang-format-3.6 - Tool to format C/C++/Obj-C code
>   clang-format-3.7 - Tool to format C/C++/Obj-C code
>   clang-format-3.8 - Tool to format C/C++/Obj-C code

General agreement among clang-format users (eg. [1], [2])
seems to be that the recommended version is 3.8.
AFAIU, that is first version with complete/correct impl. of the
included base styles, with added a few new options to support that.

[1] https://gitlab.kitware.com/cmake/cmake/blob/master/CONTRIBUTING.rst
[2] http://mesos.apache.org/documentation/latest/clang-format/

> For comparison: QGIS developers embedded a version of astyle.c in their
> codebase, so to ensure style won't change due to version of an external
> piece of software. Not that bad, as it's a single .c file IIRC.

Tell them about clang-format.

> About the specification:
>
> The clang-format document you suggest references an external entity
> (BasedOnStyle) which may make this more of a problem (what happens if
> the referenced style changes?).

That is for brevity.
For actual implementation, full version of `.clang-format` should be generated
using `clang-format -dump-config` option and BasedOnStyle commented.
I've updated RFC4.

> The format specification you propose does not mention line ending, why ?

clang-format does not enforce line endings and there is no need for that.
See EOL section I've just added to RFC4.

> About history destruction:
>
> You suggest to change .editor-config to match the new proposal, why not
> doing the contrary instead, to avoid changing too much the existing
> styles again?

I'm fine with any direction and I expected suggestions to the proposed settings.

"a standard is more important than which standard" summarises overall
spirit of the RFC4.

Although I'm not trying to sneak in style used in C++ standard library or Boost,
I do expect to avoid formatting styles exotic for any modern C++
codebases (and programmers) of XXI (eg. GNU, Whitesmiths).

> For example .editor-config requests the use of TAB, which
> are in use since a long time, why not keeping them ?

Currently, we have a mixture of tabs, spaces, 4-space indents,
2-space indents, everything really.
Year ago, the .editor-config sneaked in with 'breaking change' of
indent_size=2, new indentation width to the majority of codebase.
I take it as it is never a bad time to decide on new compromise.

Finally, as a member of the "heretic movements" [1] I just settled
with the 4-space indentation in the proposal.

[1] https://www.kernel.org/doc/Documentation/process/coding-style.rst

> Had you run tests with your suggested style to check how many lines
> would be changed ?

No, I haven't.
ATM, I'm doing my homework and getting buy-in.

Best regards,
-- 
Mateusz Loskot, http://mateusz.loskot.net