On Jul 15, 2008, at 8:22 AM, Piotr W. [email protected]
wrote:
It’s not AR. I have 2 levels: Site1Scraper < BaseScraper.
There will be many SiteXScrapers implemented by several people.
++++
From your answers I conclude it’s not possible (or at least not
recommended) to document abstract interface with RSpec.
If everyone gave up that easily we’d never improve anything 
Not sure how you get to “not possible.” Pat suggested shared examples,
which would be a perfectly good solution for part of the problem.
I think the question is what are you trying to acheive here and
whether Rspec (or any testing framework) is the right place for that
goal.
David C. wrote:
On Jul 15, 2008, at 8:22 AM, Piotr W. [email protected]
wrote:
It’s not AR. I have 2 levels: Site1Scraper < BaseScraper.
There will be many SiteXScrapers implemented by several people.
++++
From your answers I conclude it’s not possible (or at least not
recommended) to document abstract interface with RSpec.
If everyone gave up that easily we’d never improve anything
Not sure how you get to “not possible.” Pat suggested shared examples,
which would be a perfectly good solution for part of the problem.
I think the question is what are you trying to acheive here and
whether Rspec (or any testing framework) is the right place for that
goal.
I try to document public API of important base class.
Shared examples, as you said, solve part of the problem.
Since I try to develop this project in a BDD style, and specifications
are said to be - among other things - a documentation tool, it seems
reasonable to take advantage of it. Alternative is mixed documentation
of rdoc + specs.
In a perfect world I would expect to have only one documentation tool:
specs.
On Tue, Jul 15, 2008 at 10:10 AM, Piotr W. [email protected]
wrote:
goal.
In a perfect world I would expect to have only one documentation tool:
specs.
I think in this case you could provide contract tests. These would be
shared behaviors that developers can mix in to their own specs.
Consider something basic for an account:
describe “account”, :shared => true do
it “should increase in balance after a deposit” do
start_balance = account.balance
account.deposit 100
account.balance.should > start_balance
end
it “should decrease in balance after a withdrawal” do
start_balance = account.balance
account.withdraw 100
account.balance.should < start_balance
end
end
This defines the contract of an Account abstraction… you can imagine
different account types that might implement it in a way that the
actual dollar values differ. For example, fees may be applied to one
kind of account but not another.
Anyone who implements your API can include that shared example group
and verify their code against the contract you’ve defined.
Pat
On Jul 15, 2008, at 3:24 pm, Pat M. wrote:
This defines the contract of an Account abstraction… you can imagine
different account types that might implement it in a way that the
actual dollar values differ. For example, fees may be applied to one
kind of account but not another.
Anyone who implements your API can include that shared example group
and verify their code against the contract you’ve defined.
Hi Pat
This sounds like a brilliant idea - I’ve wanted so often to be able to
mix in specs for AR::Base for example. BUT - would it encourage
programming by inheritance, rather than message passing? Often it
feels unnatural to subclass someone else’s library class and use it
in my application. Subclassing a library class to pass back into
the library doesn’t bother me. For some reason it feels normal to
subclass a controller class but not an ORM class. Perhaps because a
controller is just a strategy for handling requests, and not something
you instantiate and manipulate yourself, whereas an AR model class has
business logic (handled by the app) and persistence (handled by the
framework) rolled into one?
WDYT?
Ashley
–
http://www.patchspace.co.uk/
On Wed, Jul 16, 2008 at 4:47 PM, Ashley M.
[email protected] wrote:
requests, and not something you instantiate and manipulate yourself, whereas
an AR model class has business logic (handled by the app) and persistence
(handled by the framework) rolled into one?
WDYT?
Ashley
Well, I don’t think people would fall into the trap of misusing
inheritance if you don’t give them classes to inherit from 
The
original post was about writing specs for base classes that have empty
methods. The reason that he wanted to write these empty methods was
to provide documentation for later programmers. If, however, you
provided a set of specs that defined the expected contract, people
could write whatever code they want and know that it should work
within the framework - no inheritance required. And if the framework
developer did want to provide existing behavior, he can do so by
writing modules that people can mix into their own stuff.
Now, this is speculation on my part, as I’ve never actually done this.
But I like the idea of taking DBC ideas and flipping them on their
head, defining contracts from the client-side in the form of specs.
Pat
Pat M. wrote:
On Tue, Jul 15, 2008 at 10:10 AM, Piotr W. [email protected]
wrote:
goal.
In a perfect world I would expect to have only one documentation tool:
specs.
I think in this case you could provide contract tests. These would be
shared behaviors that developers can mix in to their own specs.
Consider something basic for an account:
Thanks for the example. It carifies the issue. I will try it.
++++
BTW, do you think it’s worthwile to replace most of rdoc and other
documentation with specs?
RSpec itself comes with nice RDoc, so perhaps I want too much?