[Users] Reformatting Carpet's source code

Wed Jul 8 08:47:33 CDT 2015

Yes, clang-format is really good; it's playing in a different league than
GNU indent or other prehistoric predecessors. It turns out that
clang-format does not chase include statements nor requires knowledge about
#define statements, and can thus format each file in isolation. It uses
clang's parser, but does not construct the detailed semantic tree
structures that clang needs to resolve types. Thus clang-format stays
closer to how a human reads code than how a compiler interprets it.

Yes, older versions of clang-format had problems in some special cases.
I've encountered issues in hairy template arguments, where clang-format
gets confused about the meaning of "<" (template argument or less-than
sign?) and "&&" (binary operator or rvalue prefix?). Newer versions of
clang-format get this right; otherwise, one can use parentheses to make the
meaning clear. Note that these are really dark corners of C++, where it is
impossible to tell the difference without knowing whether certain
identifiers are types or variables, which depends on details of scoping and
namespaces and all previous include files.

Anyway -- we should easily be able to all use the same version of
clang-format.

-erik

On Wed, Jul 8, 2015 at 9:39 AM, Steven R. Brandt <sbrandt at cct.lsu.edu>
wrote:

>  On one hand, clang-format ought to be really good because it can
> leverage the clang parser and understand the code as well as the compiler.
> Other tools have to re-engineer the whole process and may not get it
> exactly right. I'm rarely completely happy with auto-format, and because of
> that I only ever apply it to small areas of code at a time.
>
> On the other hand, there is a potential version issue. I just formatted a
> simple code with two versions of clang-format I had installed on my laptop
> and got different results. The older version messed up the formatting of a
> C++11 initializer. While the C++11 issues are probably not going to be a
> problem going forward, other issues might crop up. I could easily imagine
> bits of formatting changing back and forth as two developers with different
> versions of clang updated the source.
>
> Cheers,
> Steve
>
>
> On 07/07/2015 10:51 AM, Erik Schnetter wrote:
>
> 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/
>
>
> _______________________________________________
> Users mailing listUsers at einsteintoolkit.orghttp://lists.einsteintoolkit.org/mailman/listinfo/users
>
>
>
> _______________________________________________
> Users mailing list
> Users at einsteintoolkit.org
> http://lists.einsteintoolkit.org/mailman/listinfo/users
>
>

-- 
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/20150708/b3aeddc5/attachment.html 