title: Julia function naming: When should I append a bang?
body: <p>The Julia style guide <a href="http://julia.readthedocs.org/en/latest/manual/style-guide/#append-to-names-of-functions-that-modify-their-arguments" rel="nofollow">says</a> that functions which "modify their arguments" should have their name end on a <code>!</code>.</p>
  
  <p>However, what about:</p>
  
  <ol>
  <li><p>functions that do modify their arguments, but return them to their original state before returning?</p></li>
  <li><p>functions that return a <code>Task</code> which modifies the argument when executed?</p></li>
  <li><p>functions that return such a <code>Task</code>, but when it is done, the arguments will have been restored to their original states?</p></li>
  </ol>
  
  <p>Should their names end on a <code>!</code>?</p>
  
  <hr>
  
  <p>As an example, consider <a href="https://github.com/lmshk/sandbox/blob/master/euler/lib/ExactCovers.jl" rel="nofollow">this module</a> for finding <a href="https://en.wikipedia.org/wiki/Exact_cover" rel="nofollow">exact covers</a> using Knuth's <a href="http://www-cs-faculty.stanford.edu/~uno/papers/dancing-color.ps.gz" rel="nofollow">Dancing Links Algorithm</a>. It implements a type <code>CoverSet</code> that can be populated with the subsets and then queried for the first exact cover:</p>
  
  <pre><code>set = CoverSet()
  push!(set, [1, 2])
  push!(set, [2, 3])
  push!(set, [3, 4])
  push!(set, [4, 1])
  
  find_exact_cover(set) # returns [1, 3]
  </code></pre>
  
  <p>The <code>find_exact_cover</code> function temporarily modifies the data in <code>set</code> while searching for a solution, but by the time <code>find_exact_cover</code> returns, <code>set</code> will be in its original state. Should it be named <code>find_exact_cover!</code> instead?</p>
  
  <p>Similarly, <code>exact_cover_producer</code> returns a <code>Task</code> that produces all exact covers, but when that <code>Task</code> is done, <code>set</code> will have been restored:</p>
  
  <pre><code>for cover in exact_cover_producer(set)
    println(cover) # prints [1,3] and [2,4]
  end
  # By now, set is restored.
  </code></pre>
  
  <p>Should it be <code>exact_cover_producer!</code>?</p>
  
  <hr>
  
  <p>I am aware that this might be considered subjective, so let me clarify what I am asking for: I would like to know whether there is a convention on this in the Julia community, and ideally also examples from the standard library or any packages that use either style.</p>