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:

• linearSearchFor: -- indicates how the method works
• searchFor: -- is better
• includes: -- is even better
  • is much worse; it implies a boolean result, the others do not.
    • which is much better; the others don't imply any result at all.
      • I would expect that a function called "search" returns a key/index/iterator to the first such occurrence (or even a list of such if there are multiple), and returns an error code/exception/distinguished value/empty list if there are none.

Non-Controversial Example:

• getLinearSearchPosition: -- indicates how the method works
• getSearchPosition: -- is better
• getPosition: -- is even better
• indexOf: -- sighted in other languages

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?

• That doesn't make the method you're looking at any more compact
• That doesn't breed the possibility of HappyCollisions.

---

See IdentifiersRevealIntent, IntentionRevealingSelector, IntentionNotAlgorithm.

See IntentionRevealingSelector, for Smalltalk-specific usage.

See this for a real world example of intention revealing names http://blog.eliotsykes.com/2009/05/23/intention-revealing-naming-a-real-world-example/

---

CategoryCodingConventions CategoryCodingIssues CategoryNaming