Why use a Collection instead of an Array as property when you want to modify the contents of the property?

Question

In the documentation for CA1819 under the heading "Allow users to modify a property" the documentation shows an example of an array property that violates CA1819 by making the internal array accessible through a property. They suggest a fix to this by making the array a readonly collection instead.

In all the previous examples (from the CA1819 documentation) the reason for not allowing arrays to be accessed as a property seems to be due to you not wanting to allow the caller access to the internal array. However, this last case you are providing access to modify it, so why not just use an array?

Is it just what Ryan Lamansky said here:

"The FxCop's warning is mainly there because you're giving the user's full access to the array, including the ability to assign a new one of a different size. Inexperienced programmers might not realize all of these consequences, so FxCop throws the warning."

Or am I missing something else about this?

Answer 1

I see this as it depends on what you are after. A collection in one case may be correct while in another case an array is correct or perhaps an immutable type is best or records. it all boils down to requirements.

Answer 2

I think the "Allow users to modify a property" example relates more to read/write access of the property referencing the array rather than the contents of the array itself.

The fix does resolve that issue of being able to replace the array (by removing the set declaration, making it a read-only property) but I agree that I don't see much reason to also switch from an array to a Collection<T> in that case because both offer the same level of write restriction (in fact it's possible to even change the size of a Collection<T> whereas an array size is fixed.)

I may be missing something though.

Answer 3

Thanks for your responses @P a u l , @Karen Payne MVP .

I still can't see any reason why switching to a collection is any better in the specific case mentioned in the documentation. So unless I find out later that I'm missing some important detail I won't worry about this rule violation.

Answer 4

Hi everyone, I also posted this question here: https://github.com/dotnet/docs/issues/28424 and got a response that helped to clarify the intent of the rule.

The core idea of this rule is to discourage exposing mutable or cloned data structures through properties. It is a good API design principle to keep properties lightweight in terms of execution performance for it's getter/setter AND return immutable data to justify it being a property of the object. However, as you have mentioned, there are obviously corner cases where you still want to expose mutable data through properties, especially for internal consumers such as in tests. For such cases, it is best to return the data type that best suits your need - it could be an array or a Collection<T> type, as you prefer. If you choose an array, you will need to add a source suppression for each such property, which can be avoided by using the Collection<T>, but honestly either should be fine given that you have already made an explicit design decision for the API to return mutable data.

So it seems like I'm not missing anything and what I'm asking about is an edge case and I should use source suppression or something like Collection<T> to avoid this.