In clang-format, what do the penalties do?

c++ clang-format
Scott Langham picture Scott Langham · Oct 29, 2014 · Viewed 10.4k times · Source

The clang-format sytle options documentation includes a number of options called PenaltyXXX. The documentation doesn't explain how these penalties should be used. Can you describe how to use these penalty values and what effect they achieve (perhaps with an example)?

Answer

JHumphrey picture JHumphrey · Dec 22, 2014

When you have a line that's over the line length limit, clang-format will need to insert one or more breaks somewhere. You can think of penalties as a way of discouraging certain line-breaking behavior. For instance, say you have:

Namespaces::Are::Pervasive::SomeReallyVerySuperDuperLongFunctionName(args);
// and the column limit is here:                                        ^

Clang-format will probably format to look a little strange:

Namespaces::Are::Pervasive::SomeReallyVerySuperDuperLongFunctionName(
    args);

You might decide that you're willing to violate the line length by a character or two for cases like this, so you could steer that by setting the PenaltyExcessCharacter to a low number and PenaltyBreakBeforeFirstCallParameter to a higher number.

Personally, I really dislike when the return type is on its own line, so I set PenaltyReturnTypeOnItsOwnLine to an absurdly large number.

An aside, this system was inherited from Latex, which allows you to specify all kinds of penalties for line-breaking, pagination, and hyphenation.

Related questions

How to call clang-format over a cpp project folder?

Is there a way to call something like clang-format --style=Webkit for an entire cpp project folder, rather than running it separately for each file? I am using clang-format.py and vim to do this, but I assume there is …

Read More
Where are clang-format and clang-format.py in Mac OS X with Xcode Command Line Tools installed?

I am having a hard time finding clang-format and clang-format.py on my Mac OS 10.8.5 with Xcode 5 and its Command Line Tools. I tried find / -name "clang-format.py" without luck. Are they already here somewhere hiding, or how would I …

Read More
Using clang-format in CLion

I'd like to format my code using clang-format in CLion. I've gone through the settings and haven't found any setting that would allow me to run an external command to transform code. How are such things normally done in CLion?

Read More