Method Name Suggestion: Validate a Poor Choice?

[Mike Hofer]

Please forgive the cross-post to multiple forums. I did it
intentionally, but I *think* it was appropriate given the nature of my
question.

I'm working on an open source code library to help automate and clean
up parameter validation code. It's almost ready to go into open beta.
But one last little glitch is holding me up, and that would be the
name of the factory class that serves as the entry point into the
library: Validate.

Essentially, when you invoke the methods in this thing, your code
looks like this:

Validate.That(foo,
"foo").IsNotNull().StartsWith("bar").EndsWith("baz")

This works beautifully so far, but it becomes problematic when you use
it from ASP.NET pages, where a Validate method is already defined. As
you can imagine, the compiler thinks you're trying to invoke the
Validate method on the page; so invoking one of the That methods on
the Validate class (a factory) makes no sense.

You can get around it by using an alias with the namespace and change
to Verify or something:

using NValidate.Framework.Validate = Verify;

However, this creates a lot of manual work for the developer. It would
seem that the onus is on *me* as the publisher of the library to come
up with a solution. I mean, the whole POINT of this thing is to make
our lives easier.

So here's what I'm thinking: I could change the name of the Validate
class to Verify. That gets around the whole problem with ASP.NET
pages. That leaves only the following real concerns:

1.) Verify, like Validate before it, is a *very* common word. It's
likely that it will conflict with existing method names.

2.) The product name is NValidate. (Yep, just like NUnit, NCover,
NAnt, etc.) There might be a perceived disconnect between the product
name and the primary entry point into the library itself. (Validate
vs. Verify.)

3.) The classes that validate parameters are called validators. Again,
it's the same disconnect.

My questions for you folks with far greater experience than myself
are:

1.) Is the difference between the product name and the method name
that critical?

2.) Is there a better way to name the factory class?

I'm pretty desperate for input here as this is a one-man project so
far. Any help you big brained-folks can provide will be greatly
appreciated. For those who are interested, I can provide links to the
materials and the source code under development. (I won't spam the
boards--I'm not marketing something here. I'm trying to solve a
problem, and I don't know the best way to do it.)

Again, thanks for your help.

 

[IfThenElse]

Call it nValidate

 

[clintonG]

Be more explicit with your naming, FactoryClassValidation,
CleanMyRoomValidation etc... its a judgment call to avoid becoming verbose
but the other extreme is terse naming which does not communicate or implies
unintended meanings.

Explicit Naming = Elegant Code

-
<%= Clinton Gallagher
NET csgallagher AT metromilwaukee.com
URL http://clintongallagher.metromilwaukee.com/

 

[Nicholas Paldino [.NET/C# MVP]]

Mike,

Personally, I think that you should name Validate Validator. Generally,
for my objects, I like the type names to be nouns (not verbs) and the
methods to be verbs.

I know it kind of breaks the flow you are trying to achieve, but it
would work.

 

[Mike Hofer]

Be more explicit with your naming, FactoryClassValidation,
CleanMyRoomValidation etc... its a judgment call to avoid becoming verbose
but the other extreme is terse naming which does not communicate or implies
unintended meanings.

Explicit Naming = Elegant Code

-
<%= Clinton Gallagher
NET csgallagher AT metromilwaukee.com
URLhttp://clintongallagher.metromilwaukee.com/




















- Show quoted text -

Actually, the source code itself is pretty explicit. The API, however,
provides an implementation of fluent interfaces.

For example, here are some of the class names in the
NValidate.Framework namespace:

ValidatorBase
ValueTypeValidatorBase (derives from ValidatorBase)
ObjectValidatorBase (derives from ValidatorBase)
BooleanValidator (derives from ValueTypeValidatorBase)
StringValidator (derives from ObjectValidatorBase)
ArrayValidator (derives from ObjectValidatorBase)
ConnectionValidator (derives from ObjectValidatorBase)

The method names on the validator classes are designed to help you
validate parameters using a clean, simple interface. The idea was born
out of refactoring and unit testing. (In other words, I ripped off
NUnit's Assert.That interface to refactor my parameter validation
code.)

The idea is that you write this:

Validate.That(foo, "foo").IsNotNullOrEmpty();

Instead of this:

if (null == foo)
throw new ArgumentNullException("foo");
if (string.Empty == foo)
throw new ArgumentException("Empty strings not permitted.", "foo");

 

[Samuel R. Neff]

Validate and Verify are both very common words and could easily cause
conflicts (as you noticed) and also don't really portray exactly what
is being validated.

I think NValidate would be a good choice (especially since "nv" is
very unique in intellisense and easy to type).

Normally I believe that classes should be nouns but I see where you're
going with the constraint type language, similar to the new NUnit
stuff, so using a verb here is fine in my opinion.

Sam

 

[Mike Hofer]

Validate and Verify are both very common words and could easily cause
conflicts (as you noticed) and also don't really portray exactly what
is being validated.

Agreed.

However, the library is well documented (both internally and
externally) so that it shouldn't be difficult to understand. Anyone
familiar with NUnit should be able to figure out what NValidate code
is doing relatively quickly.

very unique in intellisense and easy to type).

It would, indeed, except that it would require an intentional
deviation from a naming standard. Then again, if that deviation is
well-documented, and for a well-thought out reason, it's acceptable.

Normally I believe that classes should be nouns but I see where you're
going with the constraint type language, similar to the new NUnit
stuff, so using a verb here is fine in my opinion.

There is a precedent: the Assert class in NUnit. The big difference
between NUnit and NValidate, I think, is that NValidate implements
fluent interfaces to optimize its performance. Since NValidate might
perform multiple tests on a single parameter, and the tests are
encapsulated in a validator object, I didn't want to have to recreate
the validator object over and over again; so the validation methods
return a reference to the validator itself (unless, of course, one of
them fails, in which case it throws an exception).

Sam

Thank you for your input!

 

[Nicholas Paldino [.NET/C# MVP]]

Mike,

Here is another thought. Why not use a class with a static member
Validate and then have an internal class, or singleton hanging off the
parent class, like so:

NValidate.Validate.That(foo,
"foo").IsNotNull().StartsWith("bar").EndsWith("baz");

It would require one level of indirection, but it could be seen as an
entry point into the syntax you want.

 

[Mike Hofer]

Mike,

Here is another thought. Why not use a class with a static member
Validate and then have an internal class, or singleton hanging off the
parent class, like so:

NValidate.Validate.That(foo,
"foo").IsNotNull().StartsWith("bar").EndsWith("baz");

It would require one level of indirection, but it could be seen as an
entry point into the syntax you want.

--
- Nicholas Paldino [.NET/C# MVP]
- (e-mail address removed)

However, the library is well documented (both internally and
externally) so that it shouldn't be difficult to understand. Anyone
familiar with NUnit should be able to figure out what NValidate code
is doing relatively quickly.

It would, indeed, except that it would require an intentional
deviation from a naming standard. Then again, if that deviation is
well-documented, and for a well-thought out reason, it's acceptable.

There is a precedent: the Assert class in NUnit. The big difference
between NUnit and NValidate, I think, is that NValidate implements
fluent interfaces to optimize its performance. Since NValidate might
perform multiple tests on a single parameter, and the tests are
encapsulated in a validator object, I didn't want to have to recreate
the validator object over and over again; so the validation methods
return a reference to the validator itself (unless, of course, one of
them fails, in which case it throws an exception).

Thank you for your input!- Hide quoted text -

- Show quoted text -

I'm thinking about this suggestion, because it has merit. But I'm
wondering if this isn't possible just using namespace resolution.

Thoughts?

 

[Brian Gideon]

Please forgive the cross-post to multiple forums. I did it
intentionally, but I *think* it was appropriate given the nature of my
question.

I'm working on an open source code library to help automate and clean
up parameter validation code. It's almost ready to go into open beta.
But one last little glitch is holding me up, and that would be the
name of the factory class that serves as the entry point into the
library: Validate.

Essentially, when you invoke the methods in this thing, your code
looks like this:

Validate.That(foo,
"foo").IsNotNull().StartsWith("bar").EndsWith("baz")

This works beautifully so far, but it becomes problematic when you use
it from ASP.NET pages, where a Validate method is already defined. As
you can imagine, the compiler thinks you're trying to invoke the
Validate method on the page; so invoking one of the That methods on
the Validate class (a factory) makes no sense.

You can get around it by using an alias with the namespace and change
to Verify or something:

using NValidate.Framework.Validate = Verify;

However, this creates a lot of manual work for the developer. It would
seem that the onus is on *me* as the publisher of the library to come
up with a solution. I mean, the whole POINT of this thing is to make
our lives easier.

So here's what I'm thinking: I could change the name of the Validate
class to Verify. That gets around the whole problem with ASP.NET
pages. That leaves only the following real concerns:

1.) Verify, like Validate before it, is a *very* common word. It's
likely that it will conflict with existing method names.

2.) The product name is NValidate. (Yep, just like NUnit, NCover,
NAnt, etc.) There might be a perceived disconnect between the product
name and the primary entry point into the library itself. (Validate
vs. Verify.)

3.) The classes that validate parameters are called validators. Again,
it's the same disconnect.

My questions for you folks with far greater experience than myself
are:

1.) Is the difference between the product name and the method name
that critical?

2.) Is there a better way to name the factory class?

I'm pretty desperate for input here as this is a one-man project so
far. Any help you big brained-folks can provide will be greatly
appreciated. For those who are interested, I can provide links to the
materials and the source code under development. (I won't spam the
boards--I'm not marketing something here. I'm trying to solve a
problem, and I don't know the best way to do it.)

Again, thanks for your help.

Neat concept by the way.

I agree that this is a case where a verb name actually makes more
sense. But, along the same lines as Nicholas' suggestion and using a
noun-verb combination...

Validator.Validate.That(foo,
"foo").IsNotNull().StartsWith("bar").EndsWith("baz");

or

Validator.Demand.That(foo,
"foo").IsNotNull().StartsWith("bar").EndsWith("baz");

....where Validator is a static class and Validate or Demand is a
singleton.

 

[Nicholas Paldino [.NET/C# MVP]]

Mike,

I don't think that there is a good solution using namespaces, as you can
always put a using statement in the top of the code which will end up
causing the ambiguity that you indicated in your initial email. With a
static property/class/method, you will always need the type name as an
"anchor" from which you can hang anything off that you like.


--
- Nicholas Paldino [.NET/C# MVP]
- (e-mail address removed)

Mike,

Here is another thought. Why not use a class with a static member
Validate and then have an internal class, or singleton hanging off the
parent class, like so:

NValidate.Validate.That(foo,
"foo").IsNotNull().StartsWith("bar").EndsWith("baz");

It would require one level of indirection, but it could be seen as an
entry point into the syntax you want.

--
- Nicholas Paldino [.NET/C# MVP]
- (e-mail address removed)

Validate and Verify are both very common words and could easily cause
conflicts (as you noticed) and also don't really portray exactly what
is being validated.

However, the library is well documented (both internally and
externally) so that it shouldn't be difficult to understand. Anyone
familiar with NUnit should be able to figure out what NValidate code
is doing relatively quickly.

I think NValidate would be a good choice (especially since "nv" is
very unique in intellisense and easy to type).

It would, indeed, except that it would require an intentional
deviation from a naming standard. Then again, if that deviation is
well-documented, and for a well-thought out reason, it's acceptable.

Normally I believe that classes should be nouns but I see where you're
going with the constraint type language, similar to the new NUnit
stuff, so using a verb here is fine in my opinion.

There is a precedent: the Assert class in NUnit. The big difference
between NUnit and NValidate, I think, is that NValidate implements
fluent interfaces to optimize its performance. Since NValidate might
perform multiple tests on a single parameter, and the tests are
encapsulated in a validator object, I didn't want to have to recreate
the validator object over and over again; so the validation methods
return a reference to the validator itself (unless, of course, one of
them fails, in which case it throws an exception).

Thank you for your input!- Hide quoted text -

- Show quoted text -

I'm thinking about this suggestion, because it has merit. But I'm
wondering if this isn't possible just using namespace resolution.

Thoughts?

 

[Mike Hofer]

Neat concept by the way.

Thanks.

I agree that this is a case where a verb name actually makes more
sense. But, along the same lines as Nicholas' suggestion and using a
noun-verb combination...

Validator.Validate.That(foo,
"foo").IsNotNull().StartsWith("bar").EndsWith("baz");

or

Validator.Demand.That(foo,
"foo").IsNotNull().StartsWith("bar").EndsWith("baz");

...where Validator is a static class and Validate or Demand is a
singleton.- Hide quoted text -

I *really* like Demand as a method name. If I had to change the verb,
Demand.That() is really nice. It's nominally shorter, and it's a stong
word (stronger than Validate, in my opinion). (I'm always looking for
ways to write less code, not more. Fewer characters is a good thing,
so long as it doesn't sacrifice code clarity or quality.)

If I had to choose a noun to prefix it with, I think I'd want
something equally as strong. What about ParamRule?

ParamRule.Demand.That()

This has the advantage of making it clear that we're working with
parameters. So we end up with this:

ParamRule.Demand.That(foo, "foo")
.IsNotNull()
.StartsWith("bar")
.EndsWith("baz");

instead of this:

Validate.That(foo, "foo")
.IsNotNull()
.StartsWith("bar")
.EndsWith("baz");

From a C# perspective, that's fine; VB developers might balk at it.

Thoughts? Suggestions?

 

[Mike Hofer]

Mike,

I don't think that there is a good solution using namespaces, as you can
always put a using statement in the top of the code which will end up
causing the ambiguity that you indicated in your initial email. With a
static property/class/method, you will always need the type name as an
"anchor" from which you can hang anything off that you like.

--
- Nicholas Paldino [.NET/C# MVP]
- (e-mail address removed)

Mike,
Here is another thought. Why not use a class with a static member
Validate and then have an internal class, or singleton hanging off the
parent class, like so:
NValidate.Validate.That(foo,
"foo").IsNotNull().StartsWith("bar").EndsWith("baz");
It would require one level of indirection, but it could be seen as an
entry point into the syntax you want.
--
- Nicholas Paldino [.NET/C# MVP]
- (e-mail address removed)

Validate and Verify are both very common words and could easily cause
conflicts (as you noticed) and also don't really portray exactly what
is being validated.
Agreed.
However, the library is well documented (both internally and
externally) so that it shouldn't be difficult to understand. Anyone
familiar with NUnit should be able to figure out what NValidate code
is doing relatively quickly.
I think NValidate would be a good choice (especially since "nv" is
very unique in intellisense and easy to type).
It would, indeed, except that it would require an intentional
deviation from a naming standard. Then again, if that deviation is
well-documented, and for a well-thought out reason, it's acceptable.
Normally I believe that classes should be nouns but I see where you're
going with the constraint type language, similar to the new NUnit
stuff, so using a verb here is fine in my opinion.
There is a precedent: the Assert class in NUnit. The big difference
between NUnit and NValidate, I think, is that NValidate implements
fluent interfaces to optimize its performance. Since NValidate might
perform multiple tests on a single parameter, and the tests are
encapsulated in a validator object, I didn't want to have to recreate
the validator object over and over again; so the validation methods
return a reference to the validator itself (unless, of course, one of
them fails, in which case it throws an exception).
Sam
Thank you for your input!- Hide quoted text -
- Show quoted text -

I'm thinking about this suggestion, because it has merit. But I'm
wondering if this isn't possible just using namespace resolution.

Thoughts?- Hide quoted text -

- Show quoted text -

Good point; I hadn't thought of that.

The current class library uses the class factory (Validate) as the
very anchor point you mention. It just has that unfortunate name, and
needs something to distinguish it from the Validate method on the Page
class. Brian Gideon may have handily solved the problem by suggesting
the *very* attractive "Demand" as an alternative name for it. But I
may still offer the intervening container class as a way to get to it
for those odd scenarios where you run into naming conflicts.

It would be nice if you could omit the container class in the
resolution if you didn't need to use it. For instance, in an ASP.NET
page, you could say ParamRule.Demand.That(), but outside of pages, you
could just say Demand.That(). Having said that, I'm all for brevity in
the code, but not at the expense of clarity; if having two different
ways to access the validators would generate confusion, I'd likely
just enforce a universal interface and be done with it.

Keep that feedback coming! It's truly appreciated!

 

[IfThenElse]

How about,

ThouShell.beEqualTo().NotBeNull().StartsWith("bar").EndsWith("baz");

 

[Scott M.]

Mike,

Personally, I think that you should name Validate Validator.
Generally, for my objects, I like the type names to be nouns (not verbs)
and the methods to be verbs.

I agree and I believe it's better OO to do so. Classes get noun names,
methods get verb names, properties get adjective names, and events get
verb/tense names (ie. Validated, Validating).

Ultimately, someone has to use your API and the more intuitive your
classes/class member names are the less chance the API will be used
incorrectly.

-Scott M.

 

[Mike Hofer]

I agree and I believe it's better OO to do so. Classes get noun names,
methods get verb names, properties get adjective names, and events get
verb/tense names (ie. Validated, Validating).

Ultimately, someone has to use your API and the more intuitive your
classes/class member names are the less chance the API will be used
incorrectly.

-Scott M.

I both agree and disagree with you.

On the one hand, yes, OO principles should be adhered to whenever
possible, *when it makes sense to do so.*

However, I also believe that when it makes sense to deviate from rigid
practices, you should pick up that hammer and shatter that crystal
goblet with gusto provided that you can be reasonably sure that you
can explain your reasoning and justify yourself.

If I thought for one minute that my users wouldn't be able to
comprehend the use of this API, or its proper application, I wouldn't
be writing it this way. But my target audience is users of NUnit and
folks familiar with that particular paradigm. They're use to seeing
code like this:

Assert.AreEqual(250.00F, destination.Balance);

Consequently, parameter validation code like that provided by
NValidate shouldn't be difficult to grasp, understand, or debug:

Validate.That(balance, "balance").IsEqualTo(250.00F)

In this case, both frameworks use a *verb* as the entry point because
it simply makes sense to do so, rigid OO practices be damned. A
careful scrutiny of the source code, however, shows that in all other
respects, I've worked very hard to respect OO practices and haven't
violated them. The use of a verb as the entry point in this case is
entirely in supportof fluent interfaces; and was chosen specifically
for that reason. It's well documented, and I believe the appropriate
choice in this case.

 

[Cor Ligthert[MVP]]

Mike,

In my idea is this not validating
Validate.That(foo,
"foo").IsNotNull().StartsWith("bar").EndsWith("baz")

Maybe it is my poor Dutch English dialect, however I should call this
"Check".

Cor

 

[Brian Gideon]

I agree and I believe it's better OO to do so. Classes get noun names,
methods get verb names, properties get adjective names, and events get
verb/tense names (ie. Validated, Validating).

Ultimately, someone has to use your API and the more intuitive your
classes/class member names are the less chance the API will be used
incorrectly.

-Scott M.

Typically I would agree, but I think this is an exceptional case.
There's no sense it forcing something if doesn't "feel right".

 

[Brian Gideon]

If I had to choose a noun to prefix it with, I think I'd want
something equally as strong. What about ParamRule?

ParamRule.Demand.That()

This has the advantage of making it clear that we're working with
parameters. So we end up with this:

ParamRule.Demand.That(foo, "foo")
.IsNotNull()
.StartsWith("bar")
.EndsWith("baz");

I like it. It's better. What about Parameter instead of ParamRule?
Also, other than Demand what other properties or methods might the
ParamRule have? It doesn't feel right to create this static class
that only has one member. I'm backtracking a little bit here. I'm
thinking that having a class named Assert worked well for NUnit so why
not just Demand or some other clever, but acceptable name that doesn't
conflict with any other class that might be commonly used.

Thoughts? Suggestions?

One thing that is frustrating for me is that VB keywords use Pascal
casing. That makes it very easy to inadvertantly use a VB keyword in
the public interface (because class library authors typically use
Pascal casing for class, method, property, etc. names) forcing VB
programmers to use [] to escape the name in some cases. That's
another thing you have to be aware of when choosing names.

 

[Mike Hofer]

If I had to choose a noun to prefix it with, I think I'd want
something equally as strong. What about ParamRule?

This has the advantage of making it clear that we're working with
parameters. So we end up with this:

ParamRule.Demand.That(foo, "foo")
.IsNotNull()
.StartsWith("bar")
.EndsWith("baz");

I like it. It's better. What about Parameter instead of ParamRule?
Also, other than Demand what other properties or methods might the
ParamRule have? It doesn't feel right to create this static class
that only has one member. I'm backtracking a little bit here. I'm
thinking that having a class named Assert worked well for NUnit so why
not just Demand or some other clever, but acceptable name that doesn't
conflict with any other class that might be commonly used.

Thoughts? Suggestions?

One thing that is frustrating for me is that VB keywords use Pascal
casing. That makes it very easy to inadvertantly use a VB keyword in
the public interface (because class library authors typically use
Pascal casing for class, method, property, etc. names) forcing VB
programmers to use [] to escape the name in some cases. That's
another thing you have to be aware of when choosing names.

Demand (formerly Validate) is a class factory; it's a singleton, and
so each of its methods simply returns a different validator class
based on the argument list. Like so (watch out, real NValidate code
coming!):

using System;

namespace NValidate.Framework
{
public sealed class Demand
{
public static ArrayValidator That(Array parameterValue, String
parameterName)
{
return new ArrayValidator(parameterValue, parameterName);
}
public static BooleanValidator That(Boolean parameterValue, String
parameterName)
{
return new BooleanValidator(parameterValue, parameterName);
}
public static ByteValidator That(Byte parameterValue, String
parameterName)
{
return new ByteValidator(parameterValue, parameterName);
}
}
}

(Obviously, we're not dealing with rocket science, here. =D)

Given that it's purely a class factory, and the XML documentation
comments (which I snipped for brevity) make that pretty clear, my
reservations about it having only one distinct method with multiple
overloads are not substantial enough to warrant a complete rewrite at
this time.

Now, having said that, if someone can provide a better solution that
will be more extensible (I'd *really* like for developers to be able
to dynamically invoke their own validators at some point), I'm all
ears. The class factory design you see above is pretty restrictive;
it'll work for the first iteration, and it's extensible from the point
of view that users will have the source code and can extend the
library themselves. BUT...

What would be nice is if a 3rd party DLL could create a class that
implemented an interface or extended a base class or something and
passed that to NValidate for invocation. That would allow end-users to
write more complex test sets, and possibly more efficiently than
NValidate can execute them individually. I've figured out the idea
behind a basic interface or a function pointer approach, but the
problem arises where users want to pass *more* information to the
custom validator. I could use some help figuring out how to do that.