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 describe how to use these penalty values and what effect they achieve (perhaps with an example)?

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.