1

I will illustrate the problem with a specific case. Suppose we have a bit-flag style enumeration type defining different kinds of validations. It's tempting to define an enumerator like FULL_VALIDATION with all bits set. The most obvious (and superficial) justification for it is convenience. Users no longer need to explicitly bitwise OR possibly a large number of specific enumerators.

While such an enumerator may seem OK at first sight, certain concerns come to mind after a second thought. As the library evolves, new validation types may be added, which do not exist in previous versions. As a result, FULL_VALIDATION will imply a stricter validation than it did before. User code that runs OK on previous versions may fail with the new one. In some sense, this may categorize as a breaking change (thought I don't see it this way).

So, the question is: is such an all-encompassing enumerator appropriate? Personally, I'm in favor of defining it. The exact semantics of FULL_VALIDATION should be: do as many validations as you possibly can. By incorporating new validations into this enumerator, we are not breaking this semantics (or contract, promise, interface, whichever you prefer). There is no need to modify the documentation concerning this enumerator. In this regard, the subtleties with this enumerator are more of a feature than a bomb.

The semantics of the enumerator is inherently inaccurate and inexact. This is just what it's meant to be, and should be what users expect and want if they choose to use it. Despite being somewhat ambiguous, this is actually a quite flexible design. By using such an enumerator, you allow your code to evolve with the library, taking advantages of any new features as they appear. On the contrary, if you explicitly bitwise OR a number of specific enumerators, you are stuck with it and get none of the flexibility and evolvability.

With respect to "breaking changes" that may result from using such an enumerator, I think it's not only OK but should actually be cheered upon. A bug that fails to manifest itself is still a bug. What's really happening here is that with the new version of the library and its more powerful validations, we just managed to reveal yet another bug in user code. So, it's not an issue of the library, but of user code. Users should be happy with this. It's one of the advantages and benefits by using the FULL_VALIDATION enumerator. Last but not least, users should ALWAYS run regression tests when moving to new versions of depended libraries.

The above is what I have thought. To be sure and make informed decisions, I want ideas from you guys also.

  • Sounds like you've already answered your own question. – Robert Harvey May 19 '16 at 17:14
  • Building on what @RobertHarvey said, you might want to restructure this as a self-answered question, leaving the question proper in this post and editing out the answer reasoning into the answer section. Then your answer can be voted on separately, and you can get better competing answers as well. – Nathan Tuggy May 19 '16 at 17:47
1

It's unclear the target user in your question. So I have given my thoughts on dev users and end users. Either or both may apply.

Devs

Breaking changes are usually not considered a feature if we're talking about dev users. It will most certainly not be cheered upon when a dev updates a library only to have their code break at run time. Also, it's not too difficult in client code for a dev to construct their own static values for what they consider is "full validation", and update that flag as they are able to support new ones. (If full validation is a requirement of the system, then you wouldn't even expose the option to partially validate except for testing.)

End Users

If these validations are user-facing, and the whole purpose is to report validation errors to the user, that's only a slightly different story. Systemically, validations are good things and more errors caught is better. But end users that have to fix them are going to generate support calls/tickets when new validations are added. "Yesterday there were no errors, but today it's showing an error and I didn't change anything. Is that a bug?" I have personally gotten these calls when I added requested validations to the system. Unless (and maybe even if) new validations are announced up front, it's essentially an unplanned support issue for the end user.

convenience vs support

The FULL_VALIDATION flag is essentially a convenience object. You have to weight the value of this convenience versus the potential support issues when the functioning of the convenience changes. If it is THAT much of a convenience, then by all means use it. But if it is likely to cause support calls, then don't change it. Just add a new convenience flag (say FULL_VALIDATION_V2) and allow clients to migrate to it when they are able without breaking what they are already using.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.