Ytukyg

Is it enough for methods to be distinguished just by argument name (not type) or is it better to name it more explicitly?

For example T Find<T>(int id) vs T FindById<T>(int id).

Is there any good reason to name it more explicitly (i.e. adding ById) vs keeping just argument name?

One reason I can think of is when signatures of the methods are the same but they have a different meaning.

FindByFirstName(string name) and FindByLastName(string name)

Sure there is a good reason to name it more explicitly.

It's not primarily be the method definition that should be self-explanatory, but the method use. And while findById(string id) and find(string id) are both self-explanatory, there is a huge difference between findById("BOB") and find("BOB"). In the former case you know that the random literal is, in fact, an Id. In the latter case you're not sure - it might actually be a given name or something else entirely.

There are reasons to prefer FindById (versus a compelling one in favor of Find: Brevity).

1. Future-proofing: If you start with Find(int), and later have to add other methods (FindByName(string), FindByLegacyId(int), FindByCustomerId(int), FindByOrderId(int), etc), people like me tend to spend ages until they finally find the Find(int) method because they are looking for FindById(int). Not really a problem if you can and will change Find(int) to FindById(int) once it becomes necessary, but that is something that will maybe happen in the future - future proofing is all about these maybes.




2. Make things easier to read. Find is perfectly fine if the call looks like record = Find(customerId); Yet FindById is slightly easier for reading if it's record = FindById(AFunction()); or record = FindById(AFunction() * A_MAGIC_NUMBER + AnotherFunction()); -
   although you could argue that you have bigger problems if you reach that point.




3. Consistency. You can consistently apply the FindByX(int) / FindByY(int) pattern everywhere, but that won't work for Find(int X) / Find(int Y).

Personally, I prefer a different approach:

// Use Id<Customer> or CustomerID, depending on local coding standards

CustomerRecord Find(Id<Customer> id) 

Related: Strongly typing ID values in C#

The above is the answer to the question, the below is clarification and additional information based on feedback provided by comments.

The advantages of a simple Find all boil down to the initially mentioned Brevity, which is valued highly by some, and not so by others:

• KISS. Find is simple and straightforward, and alongside operator it's one of the 2 most expected function names in this context. (Some popular alternatives being get, lookup, or fetch, depending on context). Some schools of thought oppose unconditionally applying the KISS principle.


• As a rule of thumb, if you have a function name that is a single well-known word which accurately describes what the function does, you need a very compelling argument to prefer a function name made up from multiple words, even if the latter is slightly better at describing what the function does. See: Length vs NumberOfElements. What is and what isn't a "very compelling argument" is subjective.


• Some schools of thought aim to avoid redundancy whereever possible. If we look at FindById(int id), we can easily remove redundancy by changing it to Find(int id). It's worth mentioning that some schools of thought disagree and do embrace redundancy under various circumstances.

Regarding the suggested alternative Find(Id<Customer> id), there was an upvoted comment that heavily criticizes it. I'm including the response in this answer because similar criticism did appear in the linked question as well, meaning they are shared by multiple readers.

• 
  Concern 1: It's an abuse of generics. A CustomerId and an OrderID are not the same thing, but the implementation ends up being similar. A common approach to similar implementations is metaprogramming. Using generics for metaprogramming is their purpose, not an abuse. There is value in a discussion about either exposing or hiding the generic, something which will ultimately come down to local coding standards.


• 
  Concern 2: It doesn't stop simple mistakes./It's a solution in search of a problem The linked version absolutely does stop plenty of mistakes, with the most common one being the wrong argument order in DoSomething(int customerId, int orderId, int productId). If it's used in green-field projects there is no need to expose the underlying implementation, thus preventing even more possible mistakes. Strongly typed Ids also resolve the issue the OP asked us about.


• 
  Concern 3: It really just obscures code. It's hard to tell that an id is held in int aVariable. It is easy to tell what kind of Id is held in Id<Customer> aVariable. That's because the latter is less obscure. Knowing what a variable represents is always more important than knowing how it does so, because unlike the "how", the "what" is useful on it's own.


• 
  Concern 4: These Ids are no strong types, just wrappers. std::string is just a wrapper around char*. If a class wraps something, it does not follow that the class isn't a strong type. Using a class to wrap the implementation detail of an integer id serves the principle of making interfaces easy to use correctly, hard to use incorrectly, by removing unnecessary and harmful functionality like bitwise operations. It also provides encapsulation, which makes it a lot easier to account for new requirements such as larger IDs, leading zeros, or alphanumeric IDs. On top of that, implementing CustomerId as a class supports the single responsibility principle.


• 
  Concern 5: It's over engineered. Here's a minimal version, although I do recommend adding operator== and operator!= as well, since I find they are easier to read than Equals.

.

public struct Id<T>: {

    private readonly int _value ;

    public Id(int value) { _value = value; }

    public static explicit operator int(Id<T> id) { return id._value; }

}

Another way of thinking about this is to use the type safety of the language.

You can implement a method such as:

Find(FirstName name);

Where FirstName is a simple object that wraps a string which contains the first name and means there can be no confusion as to what the method is doing, nor in the arguments with which it is called.