cayenne-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Durchholz, Joachim" <>
Subject RE: Optimistic locking
Date Wed, 22 Feb 2012 10:58:11 GMT
> The JavaDoc could be improved upon, certainly.  There are a few
> exceptions that commitChanges() will throw, but you don't have
> to catch them if you don't want -- depends on your use.
> Of course, catching is usually nicer.  :-)

Sorry, but that's just too handwavy.
For writing professional code, anyway.

I'd need to know what exceptions can be thrown.
Under which circumstances.
As exactly as possible. ("Exact" from a caller's perspective. I.e.
in terms of things that the calling code controls.)

Of course, I can guess what exception will be thrown when.
I'll probably even be correct - I can read code after all :-)
But that's not going to cut it. I won't see what aspects of
Cayenne's behaviour are essential and what are accidental.
Accidental aspects might be changed at the drop of a hat. It would
be unwise to rely on them.
Essential aspects are those that the Cayenne team expects to be
relied upon by application developer, and that the Cayenne team
won't change (not without prominent notice and a good reason,
Actually I don't care much about Javadoc per se, I care about
having a place to turn to when I need to check what the dev team
thinks is essential. So, anything will do, even scribbled notes in
the source, as long as they are reasonably accurate and up-to-date.

I'm constantly amazed about how many projects fail to document
that properly.
If a project wonders why it isn't getting more traction - here's
one major pitfall.

Sorry, but this needed to get out.

View raw message