Why is iterating an array and destroying objects considered bad practice?

I am writing a “match-3” style game. My matching algorithm builds an array of objects which need to be destroyed. That is, after my match check, I iterate through the array, destroying the objects in it.

While I realize I should use Destroy over DestroyImmediate, I’m really curious about this comment in the reference manual:

Also note that you should never iterate through arrays and destroy the elements you are iterating over. This will cause serious problems (as a general programming practice, not just in Unity).

Unity - Scripting API: Object.DestroyImmediate

Why is this bad practice - This is exactly what I’m doing and I’d like to know what “serious problems” they are referring to. I assume an array of objects is in fact an array of references to objects, so I’m not sure why this is bad practice to delete the referenced object and what harm it will cause.

And, in light of that, how would one delete the objects which you have collected in an array if you can’t iterate them?

Thanks for any insight,


Suppose I have an array {5,4,4,3,4,6}, and I want to remove all the 4s

for( int i=0 ; i<array.length ; i++ )
    if( array==4 )

now this code will go:

  • i=0: not a 4 → Do nothing → Result: {5,4,4,3,4,6}
  • i=1: a 4 → Remove → Result: {5,4,3,4,6}
  • i=2: not a 4 → Do nothing → Result: {5,4,3,4,6}
  • i=3: a 4 → Remove → Result: {5,4,3,6}
  • i=4: i>=array.length → End.
  • final result: {5,4,3,6}

Note that not all 4s have been removed. See the problem?

This is indeed bad practice for anything that is not handled by Unity.

If you were to loop in an array of GameObject or components, this would not really matter if you use the Destroy method.

Here’s why:

As suggested by @SoundLogic above, when iterating over an array and removing objects from the array, you might end up skipping objects.

If you only use the Destroy or DestroyImmediate though, the object will be disposed of but will not be removed from your array. Which means that the iteration will got to completion. Beware though as this means that the disposed objects will stay in your array. This can be a problem if your array doesn’t only serve the purpose of destroying objects.

The best way to actually remove/destroy objects from an array while iterating over it without consequences would be to do a reverse loop as such :

for( int i=array.Count ; i >= 0 ; i-- )
    if (array.NeedsDisposing)

This way, you can remove objects in a loop without getting an out of bounds exception!

The reason why it says so in the documentation is not that the Destroy method which is not DestroyImmediate, should not be used in the iteration. The Destroy method already works with a delay. So I don’t think it would be a bad practice to use the “Destroy” method in iteration because I don’t know how this method can accidentally start “without delay”. Moreover, you cannot directly delete an element in arrays. You can just create again the array without the object you want.

But when it comes to objects, you can destroy the game objects referenced by the array, this ultimately only destroy the referenced object instead of destroying that index of the array, because you achieve this with the “Destroy” method designed to destroy the gameobject in Unity, this method does not destroy the index value of that index in the array. It has no problem with it.

I don’t see a problem in iterating over an array and calling DestroyImmediate. If anyone can name any issue it may cause, I really am curious.
The array contains references. You are not invalidating an iterator, you are not… doing anything wrong, really.