www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Pre / Post / Invariant Best Practices

reply "David Barrett" <dbarrett quinthar.com> writes:
I'm trying to wrap my head around how best to use these.

Preconditions I get:
Validate every input to my methods because I can't trust the caller.
Likewise, validate that the object is in an acceptable state *for this
method*. (Different methods might have different "valid" states: File.open()
asserts that the file is closed, while File.close() asserts that it's open.)


Invariants I kinda get:
Validate that the object is in one of the many possible valid states.  This
doesn't eliminate validating the specific state in the Precondition, but it
can simplify the Precondition. (For example, if File.filename must be set
whenever it's open, then assert this relationship in the invariant.  Then
you don't need to test both the filename and the open state in the
File.open() and File.close() Precondition -- testing one is sufficient to
prove the other.)


But Postconditions elude me:
It seems of very low value for a method to test its own output: that's like
the fox guarding the henhouse.  If I'm going to have a test, I'd prefer that
the caller do the testing to verify the method output what it expected.
Just like a method can't trust its input and needs to validate it with
preconditions, it can't trust a return value and thus must validate it, too.
After all, the return value might be "valid" from the perspective of the
method, but "invalid" from the perspective of the caller.

Granted, I can see the value of periodically asserting your state while
within some complex operation.  But by the time I get to actually returning
a value, I should have a pretty high degree of confidence that I'm returning
the right value.  And if I'm just doing a final check to verify the object
is still sound, that should be done in a class invariant, no?


So my question is: what "best practices" have you been using in reality?  I
personally use Preconditions and copious amounts of asserts.  But Invariants
and Postconditions don't seem to offer real-world value to the code I'm
writing.  Am I missing something?  Do others find that writing/maintaining
Invariants and Postconditions pays for themselves in the bugs they avoid?

-david
Jul 08 2004
next sibling parent reply "Walter" <newshound digitalmars.com> writes:
"David Barrett" <dbarrett quinthar.com> wrote in message
news:cckop5$c8g$1 digitaldaemon.com...
 So my question is: what "best practices" have you been using in reality?

 personally use Preconditions and copious amounts of asserts.  But

 and Postconditions don't seem to offer real-world value to the code I'm
 writing.  Am I missing something?  Do others find that writing/maintaining
 Invariants and Postconditions pays for themselves in the bugs they avoid?

Consider a function that sorts its input. A postcondition would test to see if the data is really sorted.
Jul 08 2004
parent reply "David Barrett" <dbarrett quinthar.com> writes:
"Walter" <newshound digitalmars.com> wrote in message
news:cckuq3$kab$1 digitaldaemon.com...
 "David Barrett" <dbarrett quinthar.com> wrote in message
 news:cckop5$c8g$1 digitaldaemon.com...
 So my question is: what "best practices" have you been using in reality?

 personally use Preconditions and copious amounts of asserts.  But

 and Postconditions don't seem to offer real-world value to the code I'm
 writing.  Am I missing something?  Do others find that


 Invariants and Postconditions pays for themselves in the bugs they


 Consider a function that sorts its input. A postcondition would test to

 if the data is really sorted.

I agree that there are times a Postcondition *could* be used, and that's a good example. But I'm not disputing it's theoretical value. Rather, I'm asking asking: How often do people really use them *in practice*? Would you say that "none", "some", "most", or "all" D functions you write use Postconditions? As a comparison, do you use "fewer", "as many", or "more" Postconditions as Preconditions? -david
Jul 08 2004
parent "Walter" <newshound digitalmars.com> writes:
"David Barrett" <dbarrett quinthar.com> wrote in message
news:ccl7qu$1216$1 digitaldaemon.com...
 But I'm not disputing it's theoretical value.  Rather, I'm asking asking:
 How often do people really use them *in practice*?

Not much right now. But I expect as people get more into D, they'll use them more. For example, look at std.format.doFormat() - it's full of nested functions!
Jul 09 2004
prev sibling next sibling parent reply Arcane Jill <Arcane_member pathlink.com> writes:
In article <cckop5$c8g$1 digitaldaemon.com>, David Barrett says...
I'm trying to wrap my head around how best to use these.

Curiously, the way I use them is completely different from that in which you use them. Could be the start of an interesting discussion...
Preconditions I get:
Validate every input to my methods because I can't trust the caller.

Oh contraire! You shouldn't use preconditions to validate USER input - because those "in" blocks will disappear altogether in a release build. You'll end up with code that only works in a debug build. Preconditions should never result in different behavior between release and debug builds. Besides which, what use is an assert message to an end-user? No, preconditions exist to help YOU find YOUR bugs. The way I use it, if the input is dependant upon user-input, then I should test for validity in the function body, not the precondition, and throw an exception or otherwise handle it if it turns out to be nonsense. The in-block is there to test whether or not my own code contains bugs. In simple terms, the in-block asserts that the input is what I *EXPECT* it to be. (And in the case of user-input, I expect it to sometimes be rubbish, and hence consider rubbish to be legal input). In this paradigm, every assert failure within an in-block represents one bug found in another part of code ... which then gives me the power to go and fix it.
Likewise, validate that the object is in an acceptable state *for this
method*. (Different methods might have different "valid" states: File.open()
asserts that the file is closed, while File.close() asserts that it's open.)

I don't think it should be an error to close a file twice. The second close should be silently ignored, and should be completely harmless. And writing to a file which is not open should surely throw a WriteError? Again, I remind you that asserts - along with in-blocks and out-blocks - will not be present in a release build. What's your program gonna do then? Crash?
Invariants I kinda get:

They're pretty easy to understand, in that they can only really be used for bug-finding.
But Postconditions elude me:
It seems of very low value for a method to test its own output: that's like
the fox guarding the henhouse.

Really? I find postconditions most useful of all. In the Int class (etc.bigint.bigint) they're used all the time. For example - there's a function which, given input x, returns the integer square root y of x, and the remainder r. The postcondition asserts that (y*y+r == x). In other words, the postcondition will tell me if the function contains a bug. Simply calling the function a few times without seeing an assert gives me high confidence that the function is okay.
After all, the return value might be "valid" from the perspective of the
method, but "invalid" from the perspective of the caller.

There is no "valid" or "invalid". Just "bug-free" or "not bug-free". That's what you're testing for.
And if I'm just doing a final check to verify the object
is still sound, that should be done in a class invariant, no?

Yes it should. But that wouldn't have helped me with the square root example, would it? Postconditions serve a different purpose.
So my question is: what "best practices" have you been using in reality?  I
personally use Preconditions and copious amounts of asserts. But Invariants
and Postconditions don't seem to offer real-world value to the code I'm
writing.

They offer value to the person WRITING the code, not value to the person USING the code.
Am I missing something?

You may possibly be missing the fact that all of these things will disappear into the ether in a release build. Never assume that an end user will have the benefit of these things in your code.
Do others find that writing/maintaining
Invariants and Postconditions pays for themselves in the bugs they avoid?

Yes, but they don't AVOID bugs - they FIND bugs. Your end-users avoid them, because /you/ fix them before those other people even see them. Arcane Jill
Jul 09 2004
next sibling parent reply "Walter" <newshound digitalmars.com> writes:
"Arcane Jill" <Arcane_member pathlink.com> wrote in message
news:cclgul$1g20$1 digitaldaemon.com...
 Oh contraire! You shouldn't use preconditions to validate USER input -

 those "in" blocks will disappear altogether in a release build. You'll end

 with code that only works in a debug build. Preconditions should never

 different behavior between release and debug builds. Besides which, what

 an assert message to an end-user?

 No, preconditions exist to help YOU find YOUR bugs. The way I use it, if

 input is dependant upon user-input, then I should test for validity in the
 function body, not the precondition, and throw an exception or otherwise

 it if it turns out to be nonsense. The in-block is there to test whether

 my own code contains bugs.

 In simple terms, the in-block asserts that the input is what I *EXPECT* it

 be. (And in the case of user-input, I expect it to sometimes be rubbish,

 hence consider rubbish to be legal input). In this paradigm, every assert
 failure within an in-block represents one bug found in another part of

 which then gives me the power to go and fix it.

Rock on, Jill! You've got it exactly right. Can I encourage you to post this in the D wiki?
Jul 09 2004
next sibling parent Derek <derek psyc.ward> writes:
On Fri, 9 Jul 2004 09:30:43 -0700, Walter wrote:

 "Arcane Jill" <Arcane_member pathlink.com> wrote in message
 news:cclgul$1g20$1 digitaldaemon.com...
 Oh contraire! You shouldn't use preconditions to validate USER input -

 those "in" blocks will disappear altogether in a release build. You'll end

 with code that only works in a debug build. Preconditions should never

 different behavior between release and debug builds. Besides which, what

 an assert message to an end-user?

 No, preconditions exist to help YOU find YOUR bugs. The way I use it, if

 input is dependant upon user-input, then I should test for validity in the
 function body, not the precondition, and throw an exception or otherwise

 it if it turns out to be nonsense. The in-block is there to test whether

 my own code contains bugs.

 In simple terms, the in-block asserts that the input is what I *EXPECT* it

 be. (And in the case of user-input, I expect it to sometimes be rubbish,

 hence consider rubbish to be legal input). In this paradigm, every assert
 failure within an in-block represents one bug found in another part of

 which then gives me the power to go and fix it.

Rock on, Jill! You've got it exactly right. Can I encourage you to post this in the D wiki?

Agreed. This is spot on, Jill. And very nicely said too. -- Derek Melbourne, Australia
Jul 09 2004
prev sibling parent reply Arcane Jill <Arcane_member pathlink.com> writes:
In article <ccmhl2$30jv$2 digitaldaemon.com>, Walter says...

Rock on, Jill! You've got it exactly right. Can I encourage you to post this
in the D wiki?

I don't know how. I headed over to Wiki4D to make the attempt, but got lost and confused. To be honest, until someone said "Let's start a Wiki for D" I thought Wiki was a free encyclopedia (although I see now that's actually called Wikipedia). It looks like there's no connection between the two. So, since my knowledge appears to be very deficient in some areas, perhaps someone can enlighten me. 1) What the hell is a Wiki? 2) Why is it called "wiki"? 3) How do you add pages to it, edit it, etc? 4) What's to stop spammers and site-vandals from doing (3)? 5) If I click on Edit, I see a plain text entry box in some weird non-HTML format I don't understand. What format is this? 6) Is there a tutorial somewhere on the web that explains all this for us Wiki-newbies? 7) What is the connection between this use of the word "wiki" and the wikipedia (if any). In short, I can't put that previous post in the Wiki. I tried, and gave up in confusion. But I give permission for someone else to post my words if they so desire. Long term - obviously the Wiki thing looks useful, so someone would care to enlighten me I promise I'll try to bring my skills up to date. Arcane Jill
Jul 09 2004
parent Andy Friesen <andy ikagames.com> writes:
Arcane Jill wrote:
 [...] perhaps someone can enlighten me.
 
 1) What the hell is a Wiki?

A website that anybody can edit, basically. The first one is the Portland Pattern Repository, which can be found at <http://c2.com/cgi/wiki> (incidently, there's loads and loads of awesome stuff buried in there. it's not hard to dive in and come back out with gray hair)
 2) Why is it called "wiki"?

<http://c2.com/cgi/wiki?EtymologyOfWiki>
 3) How do you add pages to it, edit it, etc?
 4) What's to stop spammers and site-vandals from doing (3)?

The biggest reason WhyNobodyDeletesWiki <http://c2.com/cgi/wiki?WhyNobodyDeletesWiki> is because it's so very easy to undo. Every wiki I know of stores changes made in the last few weeks or so, so anybody at all can undo it, and there are generally quite a lot more people interested in fixing it than breaking it. :)
 5) If I click on Edit, I see a plain text entry box in some weird non-HTML
 format I don't understand. What format is this?

Wikis have their own FormattingRules <http://c2.com/cgi/wiki?TextFormattingRules> Anyway, I'm sure you get the idea. It really is as simple as it sounds. :) -- andy
Jul 10 2004
prev sibling next sibling parent "David Barrett" <dbarrett quinthar.com> writes:
"Arcane Jill" <Arcane_member pathlink.com> wrote in message
news:cclgul$1g20$1 digitaldaemon.com...
 In article <cckop5$c8g$1 digitaldaemon.com>, David Barrett says...
Preconditions I get:
Validate every input to my methods because I can't trust the caller.

Oh contraire! You shouldn't use preconditions to validate USER input -

 those "in" blocks will disappear altogether in a release build.

Sorry! I didn't mean to imply otherwise. I agree, user input requires it's own type of validation. I meant to state that a precondition validates a method's input *arguments*, not user input. Preconditions, Postconditions, and Invariants are tools to pre-emptively identify bugs in close proximity to the source. I think we agree on this point.
Likewise, validate that the object is in an acceptable state *for this
method*. (Different methods might have different "valid" states:


asserts that the file is closed, while File.close() asserts that it's


 I don't think it should be an error to close a file twice. The second

 should be silently ignored, and should be completely harmless.

That's an interesting argument in itself (I take a very strict approach using the same logic as the D compiler having no warnings). But that's outside the scope of my question.
But Postconditions elude me:
It seems of very low value for a method to test its own output: that's


the fox guarding the henhouse.

Really? I find postconditions most useful of all. In the Int class (etc.bigint.bigint) they're used all the time. For example - there's a

 which, given input x, returns the integer square root y of x, and the

 r. The postcondition asserts that (y*y+r == x).

Ah, thanks. This helps me. I guess Postconditions -- like anything -- are an art. Looking over bigint_int.d helps me see that. I can see that functions whose primary value is to produce output benefit most from Postconditions. But I guess I had in mind things like Sockets (how can I confirm the data was sent?) or complex algorithms (how can I verify an XML document was properly parsed?). Of course, big functions are composed of small functions, and each of those might have its own Postconditions. Thanks for walking me through this; still trying to figure out how to properly place D in the pantheon of tools at hand. -david
Jul 09 2004
prev sibling parent Norbert Nemec <Norbert.Nemec gmx.de> writes:
Arcane Jill wrote:

But Postconditions elude me:
It seems of very low value for a method to test its own output: that's
like the fox guarding the henhouse.

Really? I find postconditions most useful of all. In the Int class (etc.bigint.bigint) they're used all the time. For example - there's a function which, given input x, returns the integer square root y of x, and the remainder r. The postcondition asserts that (y*y+r == x).

It is more than that. For finding your own bugs, a plain assert would be good enough. The post-condition is more like a promise to the outside world. You are telling publicly: this function will do that. Better than any comment: the promise can even be checked.
Jul 10 2004
prev sibling next sibling parent "Bent Rasmussen" <exo bent-rasmussen.info> writes:
To my knowledge Design by Contract is an Eiffel concept by origin. If you
want to see powerful use of contracts you should check out the Eiffel
structures library. A powerful aspect of pre- and postconditions is that
they can be inherited. Since in Eiffel you cannot assign a value to a field
from outside the object, you will need to make a set method to do this. So
you make a setter. Next someone inherits from your class, redefines the
setter, adds event hanling, but forgets to set the actual value. The
postcondition will be inherited and the contract breach will manifest at
runtime. This example, although trivial, shows that even in the simplest of
cases, a postcondition is relevant. I'm not so sure it isn't an error
(Arcane Jill thinks not), to close a file twice. It is an error in that it
isn't possible to close a closed file, no transition takes place, however
the outcome is acceptable. So it is an error without negative consequence
other than bloat or (remotely possible) an uncorrected misunderstanding of
the semantics of close (I can see it now: But the file was only half-way
closed!) Whether bloat like this should be avoided through contracts is a
matter of taste.
Jul 09 2004
prev sibling parent reply Norbert Nemec <Norbert.Nemec gmx.de> writes:
David Barrett wrote:

 But Postconditions elude me:

It is design-by-contract: Both, pre- and post-conditions are part of the *interface*. There are several aspects to that fact. In D, there seems to be very little distinction between interface and implementation, both being coded in the same file. I believe, though, that it is possible to extract the interface of a given module, using the compiler. In that case, the pre- and post-conditions should be put into the interface as well. They document how a function is to be used, and what it produces. It is understood, that pre- and postconditions should only ever depend on public functions and the function arguments. One important aspect of pre- and post-conditions is, that they are inherited along with the interface. (The the chapter "contracts") An overriding function must keep the contract of the original. It my loosen the in-contract or tighten the out-contract. Plain asserts in the body, on the other hand, have nothing to do with contracts, but are merely a kind of "checked documentation", helping in understanding the implementation code correctly. Whether design-by-contract helps you in avoiding bugs depends on your coding style. It certainly is only interesting for libraries and larger projects that define clear interfaces between individual parts. For small projects, thinking about clear interfaces often is more effort than it is worth.
Jul 10 2004
parent "Walter" <newshound digitalmars.com> writes:
"Norbert Nemec" <Norbert.Nemec gmx.de> wrote in message
news:cco50m$27n6$1 digitaldaemon.com...
 Whether design-by-contract helps you in avoiding bugs depends on your

 style. It certainly is only interesting for libraries and larger projects
 that define clear interfaces between individual parts. For small projects,
 thinking about clear interfaces often is more effort than it is worth.

True enough. One aspect of D that sometimes is controversial is I wanted to make it easy to write quick-and-dirty programs as well as provide the scaffolding for large, complex projects. That's why, for example, 'public' is the default access rule for class members, and object.d is implicitly imported. DbC is a waste of effort for Q&D programs, which is why it is optional.
Jul 11 2004