[boost] Re: Invariants Library

From: Thorsten Ottosen (nesotto_at_[hidden])
Date: 2004-01-03 03:24:49

"Dan W." <danw_at_[hidden]> wrote in message
news:bt5qns$ou1$1_at_sea.gmane.org...
> Thorsten Ottosen wrote:

{snip]
> >>Postconditions are the product your function sells, and preconditions
> >>are the price-tag.  It would make no sense to hide them in the cpp file.
> >
> > I'm aware of what you're trying to say, but we have to remember Eiffel
has a
> > different way of
> > compiling and linking.
>
> If it did it wouldn't matter. The fact is, the contracts must be in the
> open, or else they aren't contracts. In C++, "In the open" == .hpp

Dan, that is really your definition. "In the open" to me simply means
accessible in some form.

> > What if the html consisted of merely the code with assertions, just like
an
> > Eiffel short-form of the class?
> > The relaese of a new version of a library is usually a bigger step and
> > recompiling docs, should be rather trivially
> > automated.
>
> I'm not opposed to producing documentation from source. All I'm saying
> is that preconditions and postconditions of public functions belong in
> the header file.

Maybe. It could be that there are other reasons for demanding a header-only
policy. Does digital mars does not have that restriction?

> >>That's one of the vivid memories I
> >>have of working with Eiffel: you read through a class header, and every
> >>line of DBC code is worth 100 lines of dubious plain language
> >>documentation; and you *know* it's current; and, if it works, accurate.
> >
> > If you extract the docs by a tool as the last thing you do, you have the
> > same guarantee.
>
> Sure, I agree. But what's your point?

that there is on difference between an extended header file and a generated
docs.

[snip]

> > sure, that is beside the discussion. The important thing is that you
have
> > access to
> > such (up-ti-date) documentation, not whether it is an header file or
not.
>
> No. The point is that the header file is what a class advertises about
> itself, and the cpp file is what a class does not advertise.

A header file is rarely enough documentation for libraries. It is usually
enough
for "good-enough" software.

> Its
> products, services and price-list are things it advertises, therefore
> they go in the header file.
> The fact that contracts go a long way to document a class, and that
> their concurrency is guaranteed,

While this guarantee is certainly good, the most important aspect is that
the assertions are in the code and not in comments.

>and the necessity or not for the
> contracts to be in the header file for the sake of compilation and/or
> linkage, are all secondary concerns.

Really? I certainly can't tell; I would need to be a compiler writer to
know.

br

Thorsten