Intention Revealing Names

One of the SmalltalkBestPracticePatterns. (Quick note for Smalltalkers: "selector" would be used instead of "method name", see IntentionRevealingSelector)

Name methods after what the method does (or better yet, why you want whatever it does done), don't name methods after how it works.

For example: Non-Controversial Example: Thinking more about this, I realize that the original examples are poor examples, because they don't in fact reveal the intention of the method, as it is not intuitive as to what the method is returning, which is part of the intent of the method we are trying to reveal. These Non-Controversial Examples are much better at showing how to (1) reveal the intention, (2) hide the implementation and (3) give a clear hint as to the expected return type.

[These still don't reveal enough information. What does getPosition return if the search item isn't found? 0? -1? Does it throw an exception? You need to document all these cases somehow and somewhere and the name isn't sufficient. And since you need to know about error conditions to use the method, you have to look it up anyway, so there's no point in getting too worked up over the names (This is one of my problems with supposedly self documenting code). "includes" is the best of the bunch, but it's not equivalent to the other methods.]

To test a name:
Imagine a second very different implementation. Will the name work for both implementations?

"Search" and "includes" also imply different effort costs. Effort cost is often important in choosing an approach. This is one of the potential drawbacks of SingleAccessPrinciple? also. I suppose in a perfect world that would not be an issue, but it is currently something we must face.

I think this pattern is flawed, see my reasoning in IdentifiersRevealIntent for elaboration. Things should not be named after their intent, but after their essence, that is, not after why they are but after what they are. It should be self-evident that a name should tell you what something is. -- PanuKalliokoski

Note: If someone says, "Let's use IntentionRevealingNames here", they'd probably mean: "Let's ExtractMethod just to reveal intent (as opposed to doing the extraction to deduplicate)". Like a living, executing comment.

It is (or should be) implied with all selectors that they should reveal intent.

Why not just use a comment?

See IdentifiersRevealIntent, IntentionRevealingSelector, IntentionNotAlgorithm.

See IntentionRevealingSelector, for Smalltalk-specific usage.

See this for a real world example of intention revealing names
CategoryCodingConventions CategoryCodingIssues CategoryNaming

View edit of June 2, 2011 or FindPage with title or text search