[cfe-dev] clang-format and "ASCII art" formatting

[Sean Silva]

I'm not convinced that there are that many situations where this kind
of special-case formatting is ever completely necessary. Let's try to
avoid as long as possible adding things to clang-format that will
allow subjectivity in source layout ;) Let's keep things completely
automated.

Maybe it's worth teaching clang-format about this situation as a
special case? Alternatively, as Konstantin points out, putting the
returns on their own line indented would lead to an equally (ore more)
readable layout, and I think it would be perfectly acceptable for
clang-format to default to doing something like that.

Also, there are a lot of coding styles that do this kind of alignment
for nearly all declarations (e.g. for all the `=` when declaring local
variables), so by the time that clang-format is in production across a
variety of projects, I imagine that support for "aligned" layouts like
these switches will be a piece of toggleable generic functionality
(like maybe through an astmatcher or something).

A slightly more thorny case I think is distinguishing a situation
where we just have a bag of labels like

case Foo:
case Bar:
case Baz:
  return Qux;

from a situation where the case labels have some natural grouping
which leads naturally to a more condensed layout like

case EAX: case ECX: case EDX: case EBX:
case EBP: case ESP: case ESI: case EDI:
  return GPR;

An even nastier example is
<http://clang.llvm.org/doxygen/Lexer_8cpp_source.html#l02851>, where a
condensed layout is used with *comments* put in place of "missing"
labels which are handled elsewhere to maintain the logical
alphabetical alignment and exhibit that those other cases are being
handled elsewhere. Even with the benefit of an AST, supporting this
kind of thing seems extraordinarily difficult ("AI-complete"?).
However, this particular situation is *extremely* compelling, because
pretty much any other layout would obscure the fact that those
specific other letters are handled elsewhere.

The lexer example convinces me that we *will* need some escape hatch
for the formatter; I guess the question then is "does now feel like
the right time?". I think a reasonable criterion for this is "when it
is needed, implement it". I.e. when you start reformatting real code
and the result is unacceptable due some situation that can't be
reasonably addressed in an automated fashion (like the lexer situation
above).

Btw, w.r.t. bikeshedding over what the escape hatch should look like,
you can circumvent the entire issue and just make it configurable
(like passing in a regex or something). I think it is safe to have the
default inside the library be no escape hatch unless one is explicitly
provided. The clang-format commandline program can then keep a table
of common preexisting ones and use a command line switch to choose
between them (and just pick one as the default for projects "natively"
using clang-format on the command line). Remember
<http://xkcd.com/927/>.

-- Sean Silva

On Fri, Dec 7, 2012 at 11:18 AM, Daniel Jasper <djasper at google.com> wrote:
> Hi all,
>
> although I think we can make clang-format (clang/lib/Format) format more and
> more pieces of C++ according to a specific style, I am convinced that there
> are cases where automatic formatting is not the right solution.
>
> An example is:
> http://clang.llvm.org/doxygen/ParseExpr_8cpp-source.html line 60-90. Here,
> careful human thought leads to much more readable code then simply following
> a style guide.
>
> In order to handle such cases and still be able to auto-format entire files,
> I propose to add certain markers around areas of a file that clang-format
> should not touch. Does anyone have thoughts on this? How would we best
> design this? Add special comments like "// NO clang-format {"?
>
> Cheers,
> Daniel
>
>
>
> _______________________________________________
> cfe-dev mailing list
> cfe-dev at cs.uiuc.edu
> http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev
>