3

What naming convention should use when I have a method with an out parameter. I want to do this using clean code principles. So is it a good practice to include the name of the out parameter in the method name?

I want to write a couple of methods like this in which I use one of them in another method. And I want to be legibly and understandably by only reading they names.

Example:

public bool TryFindItemNameInNameDomain(out string itemName)

or

public bool TryFindInNameDomain(out string itemName)
  • What is your class called? – nvoigt May 24 '18 at 11:15
  • Honestly, I would just refactor the methods to not actually have OUT params. I know C# has them as part of the standard "Try" paradigm, but I feel like that historically was because C# didn't have support for tuples in the early days, and everyone wanted something that was in between "return a string" and "return a full blown class that I have to define somewhere". – Graham May 24 '18 at 14:59
  • @Graham: C# now allows you to define out variables inline. There's no good reason not to use them, unless you're tied to the idea that output has to emerge from the left side of your functions. Example: if (DateTime.TryParse(input, out DateTime start)) { // Do something with start. } – Robert Harvey May 24 '18 at 15:30
  • I'd discourage to add implementation details in the method/function names. Those details should be seen when inspecting the code (the function body, its signature, or simply the "idiom" they're used in). Adding implementation details in the name will force a rename if the implementation changes, and makes the code confusing to those already used to the old name. – Jesus Alonso Abad May 27 '18 at 21:50
2

For C# you need only look at the conventions already in place within the .NET framework --- specifically the various Parse and TryParse methods.

The int.Parse(string) method throws a FormatException if you pass it a string that cannot be parsed into a 32 bit integer.

The bool int.TryParse(string, out int) method returns false for every input that throws an exception when passed to the int.Parse(string) method.

If your use case falls outside of these bounds, then you don't need to utilize this pattern, and in fact you might confuse other .NET developers who are already accustomed to this pattern.

If you Find something, should it throw an exception or return null when the thing is not found? This, too, depends on the use case.

If you try to find a key within a dictionary and there is no item with that key, it makes sense to throw an exception.

If you attempt to find a record in the database, where your code doesn't have the same level of control as it would with a Dictionary object, then throwing an exception will happen more often. Reserve exceptions for truly exceptional conditions (i.e. stuff that doesn't happen often and your code can't recover from).

If you are trying to find a record from a database or some sort of data store I would say it is more idiomatic to return a null value than throw an exception. If you are really worried about how other programmers might interpret a null pointer, then wrap it in another object that has a boolean property determining whether or not something was found.

A "find" method on a data access object returning a null pointer has never been a mystery to me, even as a novice programmer. I always knew it meant "the thing you tried to find was not found."

2

I understand you are attempting to follow a convention using a TryXXX method, similar to TryParse. It's worth noting, however, that the CLR versions of TryXXX methods all operate on value types. If the method in question returns a reference type, you can dispense with the bool return value and the out parameter, and instead just return a null reference if not found.

Thus instead of

public bool TryFindItemNameInNameDomain(out string itemName)

You could use

public string FindItemNameInNameDomain()

That being said, you may be able to improve matters even more with a separate concept of NameDomain, e.g.

class NameDomain
{
    public string FindItemName()
    {
    }
}

Then your caller would need to write

var itemName = this.NameDomain.FindItemName();
2

The question here is not about if finding something should or should not throw an exception or return null, it is about how to name your methods.

It used to be so that IDE's weren't really a thing. This made it sort of okay to for instance include the return type in the method names (for the developer to remember what it's going to do). You would have something like

public string StringFindItemNameInDomain() 

You could also include public/private info. I believe, but don't quote me on this, that it is still common practice in c++ to prefix private member names with m_. Nowadays you hover on a method call and get all the information you need. The access, return type and params.

The problem you are having has to do with optimization/redundency. You want to optimize your method name for readability but don't want to have redundancies.

This ties into the IDE hovering features because if I see a call like

TryFindInDomain(out somestring);

I hover my mouse above it and notice the itemName parameter, I now know what it does. However when I see a call to

TryFindItemNameInDomain(out somestring);

I don't need to hover, I can read that as is. I think this is a matter of taste/style.

However, we might want to try and find other things in the domain as well. This is where it gets interesting. If a type in C# supports it, the method is always called TryParse/Parse. I only need to know about the existance of these 2 methods.

If you add another method to our current example like

public bool TryFindCarInDomain(out Car car) 

Now I need to know that there are 2 methods.

If I refactor those methods to this:

public bool TryFindInDomain(out string itemName) 
public bool TryFindInDomain(out Car car)

The compiler takes care of the types, I only need to know about 1 method signature that I can use to find stuff of certain types. If I ever need to find type x in there, I just try it. If the compiler tells me the type isn't available, I add another method for type x.

Therefore in my opinion it is better not to include itemName in the signature.

-1

In functionally oriented app, each method lives in a context of its class. The class in a context of its namespace. The chain of namespaces + class name + method name form a sentence that explains offered functionality. This also applies to the method parameters. Technology related names, if needed, appears at the end of the context's chain. E.g.

Spreadsheet.NumbersExporter.TryWrite( NumbersRow row, out NumbersSheet numbersSheet )

In API docs we see full signatures. Good IDEs display parameter names inline with a method calls. The information is visible.

Working with the context can be seen as a tool for dealing with redundant names. Some engineers, however, feel better with repeating "in" or "out" names in the method name. The thing is, we write code for our colleagues, so they can quickly understand it to move on.

  • 1
    This is C# not java. In C# namespaces aren't tied to web addresses. It was a severe mistake that the creators of java made many years ago. The creators of C# knew not to make that mistake. – Bent May 26 '18 at 16:32

Your Answer

By clicking "Post Your Answer", you acknowledge that you have read our updated terms of service, privacy policy and cookie policy, and that your continued use of the website is subject to these policies.

Not the answer you're looking for? Browse other questions tagged or ask your own question.