[ahlatimer]

The guidelines for Ruby are to add a bang (!) to any methods that mutate the object rather than returning a new one. That's not strictly followed, though, but for most of the commonly used standard library bits, you can be fairly certain that that is the case.

[chc]

In practice, even in the standard library, this isn't followed often enough to rely on. Here's a (possibly incomplete, since I'm writing this on the fly) list of bangless mutating methods just from Array:

  pop
  push
  shift
  unshift
  <<
  clear
  replace
  delete (and friends)
  keep_if

As an even more extreme example, IO contains precisely one bang-method, despite the fact that probably 75% of IO's instance methods are destructive.

The general rule seems to be that if there's a mutating and non-mutating version of the same method, the mutating one will get a bang, but when there's a mutating method with no counterpart, it might get a bang but probably won't.

[Argorak]

The guideline is: if your method does something that the programmer should think twice about or shouldn't use without proper knowledge (e.g. didn't read the docs), use !. An incomplete case of usages:

  - There is a safer alternative (e.g. mutating vs. non-mutating or skipped validation)
  - It should only be called once in a process (e.g. Padrino.start!)
  - It is non-reversible (many statemachine libraries use action! as the way to invoke state transitions, which might not be reversible)

This doesn't mean that every method needs to be suffixed by ! if it does something destructive. `delete` in the context of an ORM is standard, so it doesn't have a bang. The whole point of `pop` is to manipulate the receiver: no point in warning about it. IO is always destructive, so ! doesn't make sense either.