When to suffix a function by a bang!

thojanssens1

Sometimes you have two versions for a function, one returning a tuple (ok or error tuple), and the other raising. The latter will be then have a bang ! suffix.

For example Map.fetch/2 and Map.fetch!/2

But not every function that raise will have the bang suffix. Random example: Ecto.Changeset.put_assoc/4.
If the given key is not found it will raise, but the function still has no bang !.

What is the rule as to when to adopt the bang for your functions and when not?

3 comments

#naming-conventions #naming

0 2066 3

2020-09-21 10:24:20 UTC

Showing Posts 1 to 3

Show Best Posts
Show All (oldest first)
Show All (newest first)

wolf4earth

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.

Post #1

chulkilee

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.

Post #2

christhekeele

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.

Post #3

— All posts loaded —