view release on metacpan or  search on metacpan

Datum.pm  view on Meta::CPAN

=back

What are the benefits of such a gentlemen's agreement?  The code of the sqrt()
routine is much simpler (meaning fewer bugs) because it does not have
to bother with handling the case of negative arguments, since the caller
promised to never call with such invalid values.  And the code of the caller
is at worst as complex as before (one test to check that the argument is
positive, against a check for an error code) and at best less complex: if it is
known that the value is positive, it doesn't even have to be checked, for instance
if it is the result of an abs() call.

But if sqrt() is called with a negative argument, and there's no explicit test
in sqrt() to trap the case, what happens if sqrt() is given a negative
value, despite a promise never to do so?  Well, it's a bug, and it's a
bug in the caller, not in the sqrt() routine.

To find those bugs, one usually monitors the assertions (pre- and
post-conditions, plus any other assertion in the code, which is both a
post-condition for the code above and a pre-condition for the code below,
at the same time) during testing.  When the product is released, assertions
are no longer checked.

=head2 Formalism

Each routine is equipped with a set of pre-conditions and post-conditions.
A routine I<r> is therefore defined as:

  r(x)
    pre-condition
    body
    post-condition

The pre- and post-conditions are expressions involving the parameters of r(),
here only I<x>, and, for the post-condition, the returned value of r() as well.
Conditions satisfying this property are made visible to the clients, and become
the routine's I<contract>, which can be written as:

=over 4

=item *

You, the caller, promise to always call me with my pre-condition satisfied.
Failure to do so will be a bug in your code.

=item *

I promise you, the caller, that my implementation will then perform correctly
and that my post-condition will be satisfied.  Failure to do so will be a
bug in my code.

=back

In object-oriented programming, pre- and post-conditions can also use internal
attributes of the object, but then become debugging checks that everything
happens correctly (in the proper state, the proper order, etc...) and cannot
be part of the contract (for external users of the class) since clients cannot
check that the pre-condition is true, because it will not have access to the
internal attributes.

Furthermore, in object-oriented programming, a redefined feature must I<weaken>
the pre-condition of its parent feature and I<strengthen> its post-condition.
It can also keep them as-is.  To fully understand why, it's best to read
Meyer.  Intuitively, it's easy to understand why the pre-condition cannot
be strengthened, nor why the post-condition cannot be weakened: because of dynamic
binding, a caller of r() only has the static type of the object, not its
dynamic type.  Therefore, it cannot know in advance which of the routines will
be called amongst the inheritance tree.

=head2 Common Pitfalls

=over 4

=item *

Do not write both a pre-condition and a test with the same expression.

=item *

Never write a pre-condition when trying to validate user input!

=item *

Never write a test on an argument when failure means an error, use a
pre-condition.

If a pre-condition is so important that it needs to always be
monitored, even within the released product, then C<Carp::Datum>
provides C<VERIFY>, a pre-condition that will always be checked
(i.e. never stripped by C<Carp::Datum::Strip>).  It can be used to protect
the external interface of a module against abuse.

=head2 Implementation

With Carp::Datum, pre-conditions can be given using C<DREQUIRE> or C<VERIFY>.
Assertions are written with C<DASSERT> and post-conditions given by C<DENSURE>.

Although all assertions could be expressed with only C<DASSERT>,
stating whether it's a pre-condition with C<DREQUIRE> also has
a commentary value for the reader.  Moreover, one day, there might be an
automatic tool to extract the pre- and post-conditions of all the routines
for documentation purposes, and if all assertions are called C<DASSERT>,
the tool will have a hard time figuring out which is what.

Moreover, remember that a pre-condition failure I<always> means a bug in the
caller, whilst other assertion failures means a bug near the place of failure.
If only for that, it's worth making the distinction.

=back

=head1 INTERFACE

=head2 Control Flow

=over 4

=item DFEATURE my $f_, I<optional comment>

This statement marks the very top of any routine.  Do not omit the C<my>
which is very important to ensure that what is going to be stored in the
lexically scoped $f_ variable will be destroyed when the routine ends.
Any name can be used for that lexical, but $f_ is recommended because it is
both unlikely to conflict with any real variable and short.

The I<optional comment> part will be printed in the logs at routine entry