When to use exclamation mark in clojure (or lisp)?

Question

They say that use exclamation marks when naming impure functions.

But I don't exactly understand the "impure" functions. Are they

• functions change state of their arguments (via reset!, alter, java-object-methods, ...)
• functions occur side-effect (for example, print, spit, ...)
• or both?

Obviously, official clojure apis don't have bang!s on every case above. I wonder when should I put them and need your help to make my code saner.

Answer 1

I would say you don't need to put ! on every impure function. Community Clojure Style Guide recommends:

The names of functions/macros that are not safe in STM transactions should end with an exclamation mark.

So, basically, end with ! functions that change state for atoms, metadata, vars, transients, agents and io as well.

Thanks to @noisesmith for update.

Answer 2

Here is my article answering your question https://clojure.wladyka.eu/posts/when-use-exclamation-mark/

In simple explanation the rule is like that:

(create-user! ...) has additional effects if you run it more than once with the same input. For example send e-mail each time or create +1 user.

(create-user ...) wouldn’t have additional effects even if you run this many times with the same input.

If it is still not clear think about this: (create-user! ...) vs (create-user-only-if-not-exist ...).