Use of past tense (passive voice) to connote immutability? (E.g. Array.Transposed vs. Array.Transpose)

Question

[Note: The below is a bit C# heavy in its syntax and conventions, such as citing FxCop rules, because this is my background, but the intent of this discussion is to be language-agnostic and the code examples used should generally be regarded as pseudo-code. — Mike]

I think we would all agree that classes should generally be designed so that their object instances are immutable wherever practical, and the results of calling class members should be free of side effects, as much as possible.

Historical naming conventions, however, tend to use the active voice: 'GetSomething', 'DoSomehing', etc. and this is good because it states clearly what action that the class member is going to take.

I am now beginning to think, however, that members might sometimes (or possibly often) benefit by being named in the past tense to connote that a value is returned without affecting the referenced object.

For example, for a method that transposes an array, current naming styles would probably have it called 'Array.Transpose', but if this member returns a new array, without transposing the referenced object, then I think that calling it 'Array.Transposed' would be more accurate and makes it clearer to the programmer.

When working with an 'Array.Transpose()' method one might accidentally try to use code such as the following:

Array myArray = new Array(); 
myArray.Transpose();

But if the 'Transpose' method returns a new array without affecting the referenced object, then this code does nothing — that is, 'myArray' would quietly not be transposed. (I suppose that if 'Transpose' were a property, then the compiler would catch that the above is not legal, but FxCop guidelines state that a member that performs a conversion should be a method.)

But if the method were named in the past tense as 'Array.Transposed', it would be clearer to the user that the following syntax is required:

Array myArray = new Array(); 
Array transposedArray = myArray.Transposed();

Other names that I think would fit into this category would be members named 'Resized' vs. 'Resize', 'Shifted' vs. 'Shift', etc. The present tense would be used for members that affected the referenced object, while the past tense would be used for members that returned a new value without affecting the referenced object.

Another approach that is more common currently is to prefix each name with "Get" or "To", but I think that this adds unnecessary weight, while changing to past tense communicates the meaning effectively.

Does this make sense to other programmers here, or does this past tense idea sound too awkward when reading it?

Edit:

Great discussions below, I thank everyone a lot. A few points I'd like to summarize based on your comments and my own revised thinking on this follows below.

Method Chaining "Fluent" Syntaxes

Based on the discussions below, the use of the past tense is probably of some value when used on a mutable class in order to make it clear which members do, or do not, affect the internal state of the referenced object.

However, for immutable classes, which should be the majority of the cases (one would hope), I think that the use of the past tense can make the syntax unnecessarily awkward.

For example, with "fluent syntaxes" such as those created by method chaining, the use of past tense would make the code less readable. E.g., when using LINQ via C#, a typical method chain could look as follows:

dataSource.Sort().Take(10).Select(x => x.ToString);

If changed to the past tense, this would become awkward:

dataSource.Sorted().Taken(10).Selected(x => x.ToString);

Mind you, dataSource.Sorted() is actually clearer in meaning than dataSource.Sort(), because LINQ expressions always create a new enumeration without affecting the source. However, since we are fully aware of this when using this paradigm, the use of past tense is redundant and makes the "fluency" of reading it awkward for no real gain.

Use of Properties vs. Methods

A key issue that was brought up below regards the FxCop guidelines for the use of "Get" methods vs. read-only properties. E.g., FxCop rule CA1024.

Although not explicitly mentioned in that FxCop rule, the use of "To" methods would seem to apply to this rationale as well, since ToXXXXXX() methods are conversion methods. And in the case of ToArray(), the method is both a conversion method and is a method that returns an array.

Use of Past Tense for Boolean Properties

Some suggested that the past tense can connote a boolean value, e.g. a 'Succeeded' or 'Connected' property. I believe that the retorts below emphasizing the use of an 'Is', 'Has', or 'Are' for Boolean properties and fields are correct. Past tense can help in this regard too, but not nearly as much as using an 'Is' prefix. Feel free to use the past tense for Boolean properties and fields, it does help, but I think that it's even more important to prefix the name with 'Is', 'Has', or 'Are'.

Overall Conclusions?

For the issue of Tranpose() vs. Transposed(), I think that 'skizzy' got it right, suggesting that it should be Transpose() for a mutating action vs. GetTransposed() for a non-mutating result. This makes it 100% clear. But, again, I think that this might only apply for a mutuable class, such as an array.

For immutable classes, especially where a fluent method-chaining syntax might be used, then I think that this syntax would become unnecessarily awkward. For example, compare:

var v = myObject.Transpose().Resize(3,5).Shift(2);

to:

var v = myObject.GetTransposed().GetResized(3,5).GetShifted(2);

Hmmm... actually, even here it seems to make it 100% clear that the result does not affect the source, but I'm not sure.

I guess for a paradigm like LINQ where it is well known, the use of "Get" and/or the past tense is not necessary, but for a new API, it might have some value -- at first! If the API contains only immutable objects, once the user understands this, the use of "Get" and/or the past tense only reduces the readability.

So I think there are no easy answers here. I guess one needs to think about the entirety of your API and choose carefully!

-- Mike

Answer 1

Past-tense kinda sounds awkward. I think that you intended the word to be an adjective.

Here's my suggestion to the problem you asked for: instead of Transpose(), call it GetTransposed(). That way, you know that you are receiving something and not modifying the object.

Answer 2

It does make sense indeed.

What you are talking about, in my opinion, should be taken as a general rule when designing an API or a library. Only then would it offer a tangible benefit if the system is consistent throughout all of the classes.

Another issue is that in many cases users of the interfaces don't quite care about how the result is achieved.

Will Transpose() transpose the current object? Will Transpose() create a new transposed instance and return the reference to it? Or will it perhaps transpose once, cache the results in a copy and return it at subsequent calls without affecting the current object?

Users often just want to get the transposed result, which is why not many will care about the naming convention you're proposing.

But on its own right, it is a valid proposal.

Answer 3

I strongly disagree. Past-tense is awkward and is not commonly used (which is reason enough in itself not to prefer it).

If the method modified the object it was called on, it shouldn't return itself - this makes it clear that it modifies the object.

Likewise, if the method doesn't modify the object it was called on and instead constructs a new object, the method will return an object of the same type. This is a clear and already common convention.

The method signature is, in my opinion, a clearer and much more commonly used convention to indicate if the method returns a new object or modifies the callee.

Answer 4

Sounds reasonable, and there are precedents — Python has both list.sort() and sorted(seq). The first is a method, the other one is a function that acts on any iterable and returns a list.

Answer 5

In the Scala collections library, there are a few methods that are in the past tense:

• grouped returns an iterator which iterates over the elements of a sequence in chunks of n elements
• sorted returns a sorted version of the collection
• updated returns a new version of the collection with one element changed

However, I'm not sure whether this was a conscious decision or whether they simply ran out of names, because Scala's collection library is very rich. For example, there are also groupBy and sortBy methods, and the update method is special, because the compiler rewrites assignment

foo(bar) = baz

into

foo.update(bar, baz)

Older versions of Scala indeed did use update for immutable collections, but having update return a new version instead of mutating is very awkward, because you obviously have to assign the return value to something, so e.g. "updating" an entry in an immutable map would be something like

val newMap = oldMap(key) = value // HUH ??!!??

Now, it is

val newMap = oldMap.updated(key -> value)

In a language with a good type system, the types will usually tell you whether or not the routine mutates its arguments. In Haskell, for example, the type of the immutable version would be something like

transpose :: Array -> Array

whereas a mutable version would be like

transpose :: State Array

Answer 6

When I see a method/property in the passed tense I immediately assume it returns a boolean. Your proposal may make sense logically, but it just seems strange and awkward. If I have to explain to someone why it makes sense it is probably not a good convention.

Answer 7

I'm not a big fan of past-tense variable names for immutability - it's a somewhat unusual convention and I think it would cause confusion, especially for those individuals who are not particularly strong at English grammar (and I'm only half-joking there...)

Also, this conventions removes the opportunity of using past tense to denote something else which I think is more important: a description of the state of the described object, e.g. "processed-items" clearly tells you that the items in a collection have already been processed, which is important logical information to convey.

A better idea: make everything immutable. Then you don't need any fancy linguistic distinction. You know you want to :-)