[Users] Reformatting Carpet's source code

[Erik Schnetter]

Yeah, that's what I thought in the beginning -- code formatting is all
about indentation, which is handled by the tab key. But it turns out, it
isn't. I only noticed after using clang-format for some way. Code
formatting ties up part of your brain, every time you type a character, you
have to ask yourself "do I need to insert a space", "do not need to insert
a line break", "should I join these two lines again", "does this comments
need re-formatting", "should I line-wrap this lengthy expression
differently", "how do I make these lines line up nicely", etc.

With clang-format -- none of this. You type in the content you want, you
insert spaces where absolutely necessary, you save, and when you look
again, the code looks nice. And you can relax in the knowledge that this
formatting is a projection -- there's no "other way" that maybe might look
better.

Also, clang-format doesn't indent namespaces the way the tab key does, and
it doesn't make errors. Clang-format is the complete separation of form and
content, and you only have to care about the latter. Think of it as latex:
You type the text, and it will look well-formatted without requiring any
manual input. You may think that latex isn't necessary and that manually
formatted text will look just as nice -- and you're probably right, in
almost all cases manual formatting would look nice enough to do the trick.
But there is a fundamental difference between latex and manual formatting,
and it's good to have it.

So: Yes, this is worth it.

Regarding various versions of clang-format: There are (of course) also many
options you can set, although I just go with the default, which is very
good. Yes, there are probably difference between versions (improvements,
e.g. for handling template arguments). I'm sure we could settle on a
standard version, or a standard set of options.

-erik


On Mon, Jul 6, 2015 at 5:56 PM, Ian Hinder <ian.hinder at aei.mpg.de> wrote:

>
> On 4 Jul 2015, at 17:06, Erik Schnetter <schnetter at cct.lsu.edu> wrote:
>
> On Sat, Jul 4, 2015 at 10:30 AM, Ian Hinder <ian.hinder at aei.mpg.de> wrote:
>
>>
>> On 3 Jul 2015, at 23:33, Erik Schnetter <schnetter at cct.lsu.edu> wrote:
>>
>> I've come to like to use a tool to automatically indent and format source
>> code. This has several advantages -- the code has automatically a
>> consistent style, indentation errors become obvious, and one doesn't have
>> to spend time formatting the code manually while coding.
>>
>> clang-format is the best such tool of which I'm aware. It's vastly better
>> than e.g. GNU indent.
>>
>> I propose to re-format Carpet's source code via clang-format.
>>
>> Usually, changing the source code format is disruptive, since patches or
>> local modifications won't apply cleanly any more. However, with
>> clang-format, I don't think that this is an issue -- one can use
>> clang-format on the modified code (e.g. a branch), which should eliminate
>> gratuitous changes.
>>
>>
>> Please comment.
>>
>>
>> Suppose that I have a local branch with a number of commits (I do).  If I
>> want to cherry-pick something from the new reformatted master, I could add
>> a new commit to my branch which reformats everything, and cherry-picking
>> would hopefully then be possible.  To rebase my branch off of the
>> reformatted master, I would probably have to rebase it off the commit in
>> master before the reformat, then apply the reformatting myself, then rebase
>> again of the new master.  So apart from the amount of git-gymnastics needed
>> to do this, it seems OK.  More serious would be the utter impossibility of
>> diffing formaline tarballs across the change and identifying the real
>> differences.
>>
>> I hope it doesn't need to be said, but any commits which introduce
>> reformatting should be clearly labeled as such, and should not introduce
>> any other changes, as these will be lost during a rebase in which
>> formatting commits are skipped and formatting run again.
>>
>> With the above considerations, is it worth doing this?
>>
>
> Yes, it definitively is. Not having to worry about indentation and
> formatting while coding frees the mind; it is a transformative experience.
>
>
> I just press TAB in emacs to make sure the indentation is correct; it's
> not something I ever really think about.  After reading Roland's email, I'm
> more and more concerned that a large-scale reformatting of an existing
> codebase with several branches owned by different people is going to cause
> a fair amount of pain.  For a new project, I would definitely use such a
> system, and when new code is added to an existing project, but I'm not sure
> it's worth the trouble it will cause for Carpet.
>
> --
> Ian Hinder
> http://members.aei.mpg.de/ianhin
>
>


-- 
Erik Schnetter <schnetter at cct.lsu.edu>
http://www.perimeterinstitute.ca/personal/eschnetter/
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.einsteintoolkit.org/pipermail/users/attachments/20150707/da5949ad/attachment-0001.html