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

[Sean Silva]

Derp, sorry for the novel of my thought process on the issue.

tl;dr: Yes, we definitely will need it when working with any
nontrivial real codebase. Implement it when it is blocking forward
progress. Make the delimiter for "manually formatted" regions
configurable (like a regex) and have the command line tool support
various existing styles through a command line flag and not introduce
yet another "don't format this" marker.

Remember that a large contributor to clang's success is the fact that
it is sufficiently close to GCC to be able to pretty much immediately
be useful for projects that use GCC. Probably without going to the
extent of command-line compatibility with existing formatting tools, I
think that having clang-format be useful for existing codebases
without requiring the changes to their code (i.e. changing the "don't
format this" comments to some marker specific to clang-format) would
be a huge win.

-- Sean Silva

On Fri, Dec 7, 2012 at 1:20 PM, Sean Silva <silvas at purdue.edu> wrote:
> 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
>>