ClangFormat Additional Options Proposal

Hello,

I have a few options for ClangFormat to propose:

1. `BreakAfterScopeResolutionOperatorInFunctionDeclarationAndDefinition'.
Example:

  Before:

    void Namespace1::Namespace2::Class::Method(int parameter);

  After:

    void Namespace1::
         Namespace2::
         Class::
    Method(int parameter);

2. `BreakAfterReturnTypeInFunctionDeclarationAndDefinition'. Example:

  Before:

    void Method(int parameter);

  After:

    void
    Method(int parameter);

When both are turned on, this would give a neat look:

    void
    Namespace1::
    Namespace2::
    Class::
    Method(int parameter);

Since I prefer to stick to 80 column limit, I personally have this setup
turned on for every project I participate (using another formatter) as it
prevents otherwise ugly wrapping of long namespace names and function names
and makes code easy to follow. I'd really like to see these options to make
it into the next release of ClangFormat.

Looking forward to your feedback. Thanks!

Regards,
Alexander

It looks like not many people on this list are interested in this topic.
Maybe someone could refer me directly to ClangFormat developers to discuss
the proposal? Thank you.

Regards,
Alexander

It looks like not many people on this list are interested in this topic.
Maybe someone could refer me directly to ClangFormat developers to discuss
the proposal? Thank you.

Are you looking to contribute patches? It is likely that we'll eventually
add support for option #2 as it is also required by GNU's coding
conventions (see llvm.org/PR17851). However, I have not seen coding styles
that always break after "::". If you'd like that option, you might have to
put in the effort yourself. (Also, why not just define the functions inside
Namespace1 and Namespace2?)

Cheers,
Daniel

I copied Manuel and Daniel.

Hello Daniel,

Thank you for answering. OK, I might add it myself as time permits, although
I assumed that it would be quite simple to add for those who directly work
on ClangFormat given the framework that is behind.

Breaking after "::" is esoecially useful with class method definitions.
Don't have to go far to search for example, just look into Clang or LLVM
code base. A name of class could well be 40 characters long. If a method
name is around 20 characters, then you just have 20 characters left for
parentheses and parameters (assuming you've already wrapped return type
according to 1st proposed option). Of course you can wrap parameters, but
the point is that when you are scanning/looking through source code, the
"MyVeryVeryVeryVeryVeryUsefulSuperClass::" is irrelevant to you as you are
more interested in the name of method which is easier to track when it
starts from the beginning of line and not pushed to the middle of the line
by the "MyVeryVeryVeryVeryVeryUsefulSuperClass::". For the same reason GNU
decided to wrap return types. Why would we treat (routine-like in their
nature) class scope resolutions differently?

Regards,
Alexander

Hello Daniel,

Thank you for answering. OK, I might add it myself as time permits,
although
I assumed that it would be quite simple to add for those who directly work
on ClangFormat given the framework that is behind.

Breaking after "::" is esoecially useful with class method definitions.
Don't have to go far to search for example, just look into Clang or LLVM
code base. A name of class could well be 40 characters long. If a method
name is around 20 characters, then you just have 20 characters left for
parentheses and parameters (assuming you've already wrapped return type
according to 1st proposed option). Of course you can wrap parameters, but
the point is that when you are scanning/looking through source code, the
"MyVeryVeryVeryVeryVeryUsefulSuperClass::" is irrelevant to you as you are
more interested in the name of method which is easier to track when it
starts from the beginning of line and not pushed to the middle of the line
by the "MyVeryVeryVeryVeryVeryUsefulSuperClass::". For the same reason GNU
decided to wrap return types. Why would we treat (routine-like in their
nature) class scope resolutions differently?

Several reasons:
- Mostly, readability is about pattern matching. If you are used to things
being formatted like this, it is easier to read for you. If you are used to
different patterns, you find other layouts easier to read. People always
try to make arguments like "this is better because..." (sometimes adding
and "obviously"). And the answer is always: "It is not that simple".
- Vertical space: Readability is usually influenced by how much you can fit
on a screen. If your eyes can easily switch forward and back, e.g. between
a variable declaration and its use, this can help readability in places.
Yes, screens are getting larger, but this remains a factor.
- Easier/more intuitive search: Some people might be used to search for
"Class::Method". Of course you can come up with smarter queries, but this
is what people frequently do. Class name and method name kind of belong
together in some people's eyes.
- ..

However, I am not even trying to convince you to change the coding style. I
just haven't seen it in the wild (and don't know of a public coding style
that recommends it). Yes, it would be a reasonably easy change (although it
would take a few hours taking into account writing decent tests etc.), but
so are most of the others (e.g.
http://llvm.org/bugs/buglist.cgi?product=clang&component=Formatter&resolution=---&list_id=55266plus
hundreds of internal bugs/feature requests). So, it is a matter of
prioritization and this close to the bottom of my list.

Cheers,
Daniel

Regards,

Does it exist a list of current added options that are added but not yet
added to the clang format style options page?
http://clang.llvm.org/docs/ClangFormatStyleOptions.html

It says that page is for clang 3.5, but does not seem updated with more
options since last release of 3.4

That is incorrect. It is updated every time we add/change options (minus if somebody forgets). E.g. AllowShortBlocksOnASingleLine is new.

Cheers,
Daniel

Did not know that. Thanks for the info, does a changelog of the changes to
the options exist?

It is an open source project, so just look at the commit history of the option doc:

https://llvm.org/viewvc/llvm-project/cfe/trunk/docs/ClangFormatStyleOptions.rst?view=log