Note: This article is a work in progress!

Maybe the topic seems trivial and worn-out, as everyone knows that you need to create clear, unambiguous names. However, it’s still a greatly neglected area. Teams are still far from understanding that the most depends on naming. No refactoring has as much power as changing a name. It is primarily the names, if used correctly, that form what is called self-documenting code, creating a clear language in the source code of the system you are building.

The topic is described in “Clean Code”, but not as specifically as I see it, somewhat superficially and from a different perspective.

Anatomy of a Method (Function)

Today, a few words about the anatomy of a method (function). Every method has a so-called signature, which includes the name, parameters, and return type, the key components from the viewpoint of refactoring, because readability consists of all three elements – not just the name.

Moreover, it can be said that there are two types of methods:

• Methods returning a result;
• Methods not returning a result.

Methods Returning a Result

Note: The following rules do not apply to fluent interface types.

double computeSomeResult(int parameter1, double parameter2, int parameter3 …)

• The method name must always specify clearly and unambiguously what the method does and indicate what its result will be.
• Always create the method signature in the context of the class it is in (do not repeat the class name in the method name).
• Therefore, methods returning information about errors that occurred during its execution are an anti-pattern (though there is a trace number of cases when this strategy might be justified – usually when working with legacy code); many frameworks suffer from this “disease”.
• It is highly penalized to treat input parameters as a way to return a result, which most often happens in the case described in the point above.
• The method parameters co-create meaning with the name – they must complement it and be consistent with it.

Examples and Comments

List<Content> retrieveChildren(Content parentContent)

Okay! The name suggests that the children of the parameter will be searched for, and that’s the return type as well. More fluent versions (TBD to explain what this is):

List<Content> retrieveChildrenOf(Content parentContent)
List<Content> childrenOf(Content parentContent)

Or, if it were appropriate to the context, the method childrenOf could be part of the Content class, and then its signature would be:

class Content {
   List<Content> retrieveChildren() // ..
   // or more fluently
   List<Content> children() // ..
}

interface ContentProcessorResolver {
   //…
   /* @return returns a list of content tailored to the resolver */
   public List<? extends Content> resolve(Content content);
   //…
}

Bad name – it would suggest (in the context of the interface it’s in) that the result would be an object of the ContentProcessor class.

TBC…

(Text translated and moved from original old blog automatically by AI. May contain inaccuracies.)