Prefer declarative method names

Coming up with the right name for a method can be a challenge even if you’re sure you know exactly what it should do. All too often, I find that part of the reason why I’m having trouble choosing a name is that I haven’t really decided the purpose of the method.

Of course, if you’re not sure exactly what the method should do, that’s a problem you need to solve before you get to the part of choosing a good name for it.

Assuming you know what the method should do, now you get to decide on the name for that method. How do you choose a good one?

Consider the following method names:

• IsPreMarkdownRelease(Version version)
• ConvertWithTypeConverter(string value, Type type)
• EndsWithFileExtension(FileInfo file, string extension)

These are all implementation centric method names that reveal something about the implementation used in the underlying system - the names focus on how the question is answered, not on the question itself.

These names are poor because they break encapsulation, revealing implementation details, and because they tightly constrain future implementations.

Each of those method names can be replaced with a much better name that more clearly reflects the question being asked without revealing implementation details.

IsPreMarkdownRelease

IsPreMarkdownRelease(Version version) is trying to answer the question “Does this version of our application support Markdown?”.

This name is implementation specific because it focuses on how the version is used to make the decision: prior to a specific release, no support for Markdown; after that point, Markdown is supported. All of the logic for the decision is included in the name. This approach also implies that the test for a feature that’s no longer supported would be defined IsPostBBCodeRelease(Version version).

A better signature for these would be SupportsMarkdown(Version version) and SupportsBBCode(Version version), concentrating on the question that’s being answered and not on the way the decision is made. This allows future implementations to change their implementation and also permits consistency across other features that use different rules.

ConvertWithTypeConverter

ConvertWithTypeConverter(string value, Type type) is trying to convert a string value into a different type.

This name is implementation specific because it focusses on the internal use of a TypeConverter, precluding other conversion techniques (such as the use of a constructor that takes a single string parameter, special handling for nullable types or support for enumerations).

A better signature for this would be ConvertTo(string value, Type type), keeping the focus on the functionality. If you’re working with a language like C# with extension methods and generics, you might even rewrite this as value.As<Type>().

EndsWithFileExtension

EndsWithFileExtension(FileInfo file, string extension) is trying to decide whether the supplied file is of the specified type.

Not only is this name implementation specific, revealing that the decision is made based on what extension the file is using, it has significant limitations because many file types use multiple different extensions. A file named demo.html is still an HTML file, even though it wouldn’t match .htm; a file named readme.markdown is still Markdown even though it wouldn’t match .md.

Part of the problem with this design stems from its primitive obsession, inferring the file type based on the file name ending with a specific string.

A better signature (assuming use of a C# extension method) would be file.HasType(FileType fileType), making use of a proper semantic type. The FileType would take care of the exact test required, cleanly allowing for support of multiple file extensions where needed.

Conclusion

When you’re naming your methods, favour a declarative approach where the name of the method describes the service it provides, not the approach used for the current implementation. Your method names will be easier to understand, you’ll be free to vary the implementation, and your future maintenance burden will be lower.