In clang-format, what do the penalties do?

Question

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 descr

Answer 1

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.