Enum formatting changes - polly automatic formatting verifier

[Alp Toker]

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