Indicating status of methods

[Jim Munn]

Tim;

Your book looks like just the sort of thing I have been looking for. I have
a fair amount of experience in FoxPro/Visual FoxPro, and am working on getting
up to speed in VB and ASP.

One thing I'm curious about is when to raise errors vs returning some sort
of status. For example, in a Windows DNA app, I have a VB COM object with
an AddUser method. The add user method needs to confirm that the new user's
email address is unique in the system, add the user, and return the user's
generated integer ID. How should that method call indicate that a duplicate
email was found? Is it preferred to raise and error, or return a status value?
i.e.

'returns new user ID
Public function AddUser( ByVal strEmail as String ) as Integer
'code code code
'duplicate email found
err.raise ERR_DUPLICATE_EMAIL

or

'returns status integer value, user ID set by reference param
Public function AddUser( ByVal strEmail as String, _
ByRef intID as Integer) as Integer (or an enumerated type)
'code code code
'duplicate email found
AddUser = STATUS_DUPLICATE_EMAIL

Which method is going to make it easier for someone calling the method to
be able to deal with it? Which will work better in an MTS environment? Is
this the sort of thing that should be done consistently throughout an application?
(I assume it should, I'm just trying to figure out the best approach)

Thanks;

Jim

[Tim Patrick]

Generally, when you are writing a routine that is private to a class or to
an application, it is fine to return a result code indicating the status.
However, if you are writing a component with methods called from outside
of the component, you should raise errors (and document those error codes).
The goal in a component is to completely separate the inside of the component
from the outside world. Raising error codes helps accomplish this.

You should get into this habit now because Next Generation Windows Services
(NGWS), which works hand-in-hand with VB.NET, requires that errors are reported
by raising them, not by returning status codes. This makes error reporting
consistent.

It is acceptable to return a status code from a method if it is not really
reporting an error. For example, let's say you write a method that returns
the full name of a state when you pass it the two letter abbreviation of
the state.

sFullName = objGeog.GetStateName("MT") ' Returns "Montana"

It is valid to document this routine so that it returns the string "???"
when an unknown state abbreviation is passed. Or, you could have it raise
an error. If you are developing such a component for a single project, and
one of these styles meets your needs, you can use either one. Just be sure
to document the way in which invalid results or errors are processed.

In the example you give, that of adding a user to a set, it is probably best
to raise the error, since not adding a user is a big deal, much more than
returning "???" for a state name.

-----
Tim Patrick
tim@vbstyleguide

[Jim Munn]

Tim;

Thanks for the reply. This is the best explanation I've gotten on this topic
so far. I've been asking around on Compuserve, universalthread.com and some
newsgroups, but haven't gotten many good responses. BTW, I'm gonna go order
your book now. Hopefully its full of more good stuff like this.

Jim Munn, MCP
Visual Data Solutions


"Tim Patrick" <tim@vbstyleguide.com> wrote:
>
>Generally, when you are writing a routine that is private to a class or
to
>an application, it is fine to return a result code indicating the status.
> However, if you are writing a component with methods called from outside
>of the component, you should raise errors (and document those error codes).
> The goal in a component is to completely separate the inside of the component
>from the outside world. Raising error codes helps accomplish this.
>
>You should get into this habit now because Next Generation Windows Services
>(NGWS), which works hand-in-hand with VB.NET, requires that errors are reported
>by raising them, not by returning status codes. This makes error reporting
>consistent.
>
>It is acceptable to return a status code from a method if it is not really
>reporting an error. For example, let's say you write a method that returns
>the full name of a state when you pass it the two letter abbreviation of
>the state.
>
> sFullName = objGeog.GetStateName("MT") ' Returns "Montana"
>
>It is valid to document this routine so that it returns the string "???"
>when an unknown state abbreviation is passed. Or, you could have it raise
>an error. If you are developing such a component for a single project,
and
>one of these styles meets your needs, you can use either one. Just be sure
>to document the way in which invalid results or errors are processed.
>
>In the example you give, that of adding a user to a set, it is probably
best
>to raise the error, since not adding a user is a big deal, much more than
>returning "???" for a state name.
>
>-----
>Tim Patrick
>tim@vbstyleguide
>