eBook: 5 Essential Functions of 3D ACIS Modeler
Free eBook - How to Successfully Develop, Deploy & Support 3D Applications

Receive Posts by Email

Enter your email address:

When Is a Point Not Necessarily a Point?

Answer: when it’s a 'HappyPathPoint'.

Happy New Year everyone! I left off my last post with a dilemma: I wanted to design the interface for a function that people will call when they want to find the closest point on a surface to a test point. The problem is that the answer to this question is only usually a single, isolated point. Every now and then the answer is a set of (more than one) points. For example, all the points on a spherical surface are 'closest' to its center. So how does one design the interface so that the person writing the client code naturally accounts for this subtlety, while not forcing him to deal with an awkward interface?

I already stated that the wrong thing to do is to simply document the subtlety and hope the customer will notice it. A better solution is to (in addition to documentation) make the name of the function reflect the subtlety: prefer 'FindAClosestPoint' over 'FindClosestPoint'. The problem with this idea is that it doesn’t actually deal with the problem – how is the customer to tell if he’s on the happy path, or has run into the complex condition? And again, it relies on the customer noticing that something is up (rather than having the compiler tell him).

My preferred solution (which we first thought of while working on an ACIS project to make our internal interfaces more robust) is to introduce a new object called a 'HappyPathPoint'; the idea is that the function returns this object rather than a raw point:

happy_point_code1

As you can see, HappyPathPoint encapsulates both possible answers: if IsPoint() returns true, then the answer is (the typical case of) an isolated point and it’s safe for the customer to use the Value() method to get the point. If IsPoint() returns false, however, then the answer is (the extremely rare case of) a more general point set, and the customer should use a different branch in his analysis code:

happy_points_code2

In reality, the customer’s initial implementation for the branch where IsPoint() returns false will simply be to throw an error (and put a project in the backlog to think about what his algorithm should do). This is still a big improvement over the case where the customer’s code ignores the subtlety – what was previously a subtlety is now simply an extra question about the answer, and the code for dealing with the atypical case is isolated at the point where that case is first introduced.

One interesting question in all this is "What should the behavior of Value() be if it is called before IsPoint() has been called?" I see three possibilities:

A) Silently return an arbitrary point in the point set B) In release builds, return an arbitrary point. When contract checks are on, throw. C) Always throw

My preferred answer is B, especially if it is used in conjunction with a code coverage tool that ensures that you test suite will always hit the (invalid) call to Value() (with contract checks turned on, of course). The reason that this works is that the question I asked was NOT "What should the behavior of Value() be if it is called when IsPoint() is false?" That case will only show up in the atypical situations, and so typically won’t be hit in customer testing. The contract is that the customer must validate that the HappyPathPoint truly represents an isolated point before calling Value(), even if the HappyPathPoint happens to be an isolated point. This ensures that the client code is correctly written, even if none of its test cases hit the atypical case.

For those of you who speak C#, you should see similarities with the 'nullable' class that allows one to wrap a value class up into something that can be tested against null. As with nullable, the compiler will warn you if you try to use a HappyPathPoint where a Point is expected. HappyPathPoint is more powerful than nullable, however: nullable doesn’t protect (as a contract check) against an untested call to Value(), and it doesn’t provide an alternative answer.

I hope that I’ve convinced at least someone out there that this is a good idea. I don’t think it’s overly burdensome, and it makes the subtlety obvious in the interface. It is important not to adopt this idea as a one-off, however – if you’re going to use it, it should be implemented uniformly across your interface. The code snippets above are just an example; an interesting thing to try might be to write a HappyPath template class.

The last thing I want to say is that we’ve been thinking about this idea for years, and still don’t have a good name!! Any ideas for a better one? 'PointCandidate' maybe?

 

Tags: 

See comments

Request an evaluationREQUEST AN EVALUATION

Download technical whitepapersDOWNLOAD TECHNICAL WHITEPAPERS

Read the Spatial Blend newsletterREAD SPATIAL BLEND NEWSLETTER

Watch technical webinarsWATCH TECHNICAL WEBINARS

Featured Video

Featured Video


Learn more about Spatial's products and services.

Click thumbnail to watch video

Customers

Bricsys
Build IT
ARA
AutoDesSys
AWR
Agilent
Alibre
Ansoft
Ansys
AVL
Biesse
AlmaCAM
BCT
Bosch-Rexroth
Breuckmann
Aicon

eBooks & Whitepapers

eBooks & Whitepapers

Download technical eBooks and whitepapers on topics including industry challenges and product solutions.

Spatial Facebook Spatial Twitter Spatial LinkedIn Spatial YouTube Spatial Blog RSS

SPATIAL BLEND NEWSLETTER

A quarterly e-Newsletter highlighting industry trends, and includes articles from Spatial developers. Sign up to receive The Spatial Blend.