Does including prepositions at the end of method names follow or detract from normal C# API design?

Question

I know this sounds like a subjective answer, but I will try to make the question as objective as possible, because an objective answer to the question would be the most helpful.

I recently had a code reviewer point out that I have a habit of including prepositions at the end of my methods. Here's a recent method I wrote as an extension method to the Point class:

var rectangle = new Rectangle(0, 0, 2, 2);
var point = new Point(3, 1);

var result = point.DistanceTo(rectangle);

My code reviewer mentioned that the method should be point.Distance(rectangle). I've always considered this subjective and a matter of style. However, I have noticed more .NET API design going in this direction. For example, with NUnit's Fluent Interface, you have:

Assert.That(result, Is.EqualTo(1.0));

I have also seen this with Linq:

list.CopyTo(anotherList);
list.IndexOf(item);
list.RemoveAt(0);

Is there any settled or consistent way that .NET and/or Third Party API designers use prepositions at the end of methods? Or is it just a matter of style, and subjective? Has the API design in the .NET framework itself evolved with this policy, or has it always been in place?

Armbruster

This is the sort of rubbish with which I shall not put up (Churchill) >;-) – Habergeon

Answer 1

Prepositions are fine, as long as the object of the preposition is the corresponding argument (usually the first, never the this argument of an extension method).

An example where it might be an argument later than the first:

array.CopyCountedTo(count, destination);

To answer your question about whether this has evolved with .NET, no it hasn't.

Prepositions in function names are far more widespread than Microsoft (e.g. Java has string.charAt and string.indexOf), also .NET has been using it a lot longer than LINQ (e.g. ArrayList.IndexOf in .NET 1.0).

Perdita

Answer 2

Agreed, it is subjective but I go with the premise that I don't want to have to "Go To Definition" to work out what a method call does. The name shouldn't expand into a novel but being descriptive certainly doesn't hurt.

Lasonde

Answer 3

My personal view on the matter is that prepositions enhance the meaning of the method name. I would never use them in property names, as they almost always seem to imply an action or calculation. To use the examples you offered from the framework:

RemoveAt clearly implies that it operates using a position, while Remove is vague; you don't discover its true meaning until you examine the parameters.

CopyTo implies both duplication and movement, whereas Copy alone only clearly implies duplication.

IndexOf tells us both the meaning of the return value and the method's parameter, while Index only hints at the return value.

So yeah, to summarise, I think it's perfectly legitimate -and- improves the readability and intuitiveness of code.

Phobos

Answer 4

As you note, this is subjective, but I like to do this, and the fact the Linq uses it strikes me as an implicit approval from Microsoft.

Hallucination

I don't believe one needs to get approval from Microsoft for anything because if they did a world of programmers would be in trouble. I do agree though that this is definitely a matter of style. – Abran

I know we don't need approval from Microsoft, but they write all the .Net library code, and so by default provide a standard that we are all exposed to. That they have started using this notation in new code (LINQ) implies that they think it's a reasonable thing to do. – Hallucination

Answer 5

I think the best and even historical approach that method name should have a verb. Because a method is an act, not a thing. This verb tells you a lot what method actually do (find, try, add, remove etc.)

I know you asked about prepositions. So considering exactly your example with noun-method Distance(), I feel it confusing. Ok, distance. What is about it? If you see verbs will make your listings bigger and harder to read, then prepositions may become that powerful tool to help here. They are short and informative.

What if method would be a Vector. Its ambigious. VectorTo, VectorFrom - prepositions help. ConvertToMesh() is long, Mesh() is too abstract, but ToMesh() is both short and clear.

One more plus of prepositions is a hint that method has required parameter. E.g. GetBy() makes clear that it expects something.

Cerebroside