Enum formatting changes - polly automatic formatting verifier

[Daniel Jasper]

I have run a few numbers correcting my regular expressions based on
Tobias's feedback (allowing 100 characters for enumerators to account for
the whitespace etc.). I used the initial indentation in order to classify
the context (assuming inside classes and functions enums would be
indented). The numbers I get are:

No indentation, all on one line: 208.
No indentation, one per line (might fit one line): 180
Indentation, all on one line: 260
Indentation, one per line (might fit one line): 258

So, still a pretty even split and I don't see any correlation with the
context.

I can see the argument about comments, but
a) I don't think they constitute a strong reason. Especially with the
availability of automated formatting, you need only 1 or 2 additional
key-strokes to add comments to a single-line enum.
b) You might actually make the argument the other way: If comment-less
enums are put on a single line, you as an interface designer might be
encouraged to write comments in order to point out the individual
enumerators. :-)

All in all, my opinion is that it doesn't matter enough to validate a
separate style flag or a more extensive discussion. I am happy to revisit
if we get more data on this being a problem.



On Mon, Jan 6, 2014 at 7:35 AM, Alp Toker <alp at nuanti.com> wrote:

>
> On 06/01/2014 06:09, Alp Toker wrote:
>
>>
>> On 06/01/2014 04:05, Daniel Jasper wrote:
>>
>>> However, even based on your numbers, it is an even split. You find 259
>>> cases in favor of single line formatting and 272 cases in favor of one
>>> enumerator per line. That is as close to a break-even as it gets.
>>>
>>
>> Without weighing in on any other part of the discussion, I wonder if its'
>> the _context_ of these uses that determines what style developers are
>> using. If so (and you'd need to confirm this by sampling where the 259 /
>> 272 cases appear) then we have a very good rule of thumb to classify and
>> get it right every time.
>>
>> What I have seen is that one line enums, and equally one line function
>> definitions, are the prevalent convention at class scope and local scope
>> lexical contexts, whereas they are very rare at TU / namespace context
>> (modulo automated clang-formatted code that has been committed in the last
>> few months -- you should really sample the codebase from a revision around
>> a year ago to avoid sampling bias).
>>
>> If it holds true, I think there's a semantic value to that as well --
>> enums with global scope and visibility often correspond to other lists such
>> as the LLVM dyn_cast type system, so a strict one-line-per-enumerator
>> convention makes code review easier, and reduces churn when a new
>> enumerator is added or removed, flipping from one-line to multi-line style.
>>
>> Local enums are usually just a shorthand to avoid hard-coding constants
>> in the function body and it makes sense to have them on one line.
>>
>
> Another "semantic" explanation for how this convention appeared in LLVM,
> and why it makes sense to support it in formatting tools: Enumerators at TU
> / namespace scope are far more likely (i.e. almost always) to have
> visibility and be part of the API.
>
> There's an expectation that core "top-level" enums should have individual
> doc comments, even if there are only two or three enumerators. Bunching
> them into one line sends the wrong message and on a practical level makes
> it harder to add documentation post-review just before committing.
>
> Ditto adding drive-by docs to existing code -- if you have to split up the
> enum by hand the to document one entry, the effort barrier is raised higher
> than just writing "///< Indicates such and such", svn ci.
>
> On the other hand nobody wants or expects docs for an enum { ON, OFF } in
> a function local scope and those reall benefit from being on one line every
> time.
>
> Daniel, is this making sense from your POV?
>
> Alp.
>
>
>
>
>> Does clang-format have the smarts to identify the scope context in which
>> the enums and function definitions appear?
>>
>> This is something I'd really like and I think would comprehensively match
>> the prevalent coding style in LLVM today, as well as WebKit and presumably
>> other projects too.
>>
>> Alp.
>>
>>
>>
> --
> http://www.nuanti.com
> the browser experts
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20140108/2ffeecb2/attachment.html>