When to suffix a function by a bang!

From my perspective a good rule of thumb is:

• is there a non-raising version of the function?
• is it a realistic scenario that the passed data might lead to a raised error?

Let’s inspect your examples with these rules.

Map.fetch!/2

• is there a non-raising version of the function?
  Yes - Map.fetch/2
• is it a realistic scenario that the passed data might lead to a raised error?
  Yes - as Map operates on maps, these might or might not contain the given key

Ecto.Changeset.put_assoc/4

• is there a non-raising version of the function?
  No
• is it a realistic scenario that the passed data might lead to a raised error?
  Noish - passing an invalid key is certainly a programmer error and should be caught as early as possible

So in that sense it makes sense that Map.fetch!/2 has a bang and Ecto.Changeset.put_assoc/4 has not.

Having no bang suffix doesn’t mean it will never raise an error for any input.

• If my function needs to return error tuple - then make it ok/error tuple, not returning nil.
• If I need the function used in pipe a lot (by the nature of the function - such as it’s for data transformation) - then create bang version.

There is another school of thought - e.g. make every function to return ok/error tuple and use “optional” type like wrapper.

Bangs in Elixir, as well as Ruby, are a way of indicating there is a similar, safer way to perform an operation. The intuition I’ve developed around them is:

• When writing an API, present bang variants of functions for operations where both safe and unsafe versions have strong use-cases.

• When choosing a variant, use the existence of the bang as an opportunity to ask yourself if you might really want the safer version.

• When reading code with a bang variant, assume the author assessed the risk/failure modes in play, and chose the bang variant for some hopefully evident and important reason.

Not much more to it than that! It’s mostly a convention for developers to communicate a decision of caution and careful thought across time and space.

The only real rule is that there shouldn’t be a bang function without a non-bang equivalent. The bang doesn’t represent danger so much as an important decision made with intent, so it must be something that you decided to do in contrast to a more benign option.