Re: ODBC app in Ruby - I don't believe it.

On Friday, October 15, 2010 06:57:42 pm Dave Howell wrote:
> On Oct 14, 2010, at 23:18 , David Masover wrote:
> > So, I hate to say it, but...
> >=20
> > These things are open source. The source is open. More than that, Haml
> > has a decent test suite, which is always a good place to look when you
> > want to know how to use some code.
>=20
> I don't know why you hate to say that.

Because in a way, it's admitting that the documentation isn't sufficient, a=
nd=20
it's also implying that you _should_ dig into the source code, that this wo=
uld=20
be a perfectly normal thing to do.

That's workable, but certainly not ideal. I hate to say it because I don't=
=20
think people should have to dig into source code to get stuff done -- but i=
t=20
is nice in that you _can_ do that.

> > But the point is, while good docs are a good thing, I think working and
> > readable code is at least as important.
>=20
> I would agree with that.
>=20
> But reading the code fundamentally tells you WHAT the code does. I look to
> the documentation to find out WHY?

I don't see how that's a problem in the Haml case.

Let me put it this way: I'm not a Haml developer, never have been, but that=
=20
took me almost no time to find, and it does make sense to me why it'd be th=
at=20
way. Specifically, it makes sense that you'd have a template object that=20
represents some sort of "compiled" form of a template (or at least parsed=20
form) so that you can efficiently combine that with a given environment (th=
e=20
self and locals arguments), rather than re-parsing the template on every=20
request.

This is far from just a Ruby thing -- in particular, I know that Java's JSP=
=20
files actually get compiled to .class files, just like any other Java sourc=
e.

> There was nothing in the Sequel documentation that told me how I could get
> it to start identifying UUID codes as "type uuid" instead of pretending
> they were strings. But the code was fairly readable, and after following a
> few class definitions back up into the code, I eventually found a section
> that had a case statement regarding db types and Ruby types. and I figured
> out what to add to get it to give me UUIDs. There were still a few parts
> where I was scratching my head and going "What does this part do?"

Right -- and that makes sense. Documentation generally covers the public AP=
I.=20
If you're hacking on the source, you get to keep both pieces when it breaks=
=2E=20
It would be nice if there was better documentation as to where to get start=
ed,=20
for people who do want to play with the source, but ultimately, if you're=20
playing with the source, the goal should either be a fork or a patch, proba=
bly=20
a patch.

> It's quite possible that the answer on how to get Haml to interpret stuff
> was staring me in the face at some point, and I missed it. I'm afraid that
> doesn't change my point at all.

Actually, it does entirely. It changes your point from "I can't believe Rub=
y=20
won't let me do this," or "I can't believe Ruby makes it so difficult to do=
=20
this," to "I might have missed how to do this." One is a statement about th=
e=20
tool itself -- the language, the framework, or the community behind it -- a=
nd=20
the other is a statement about your ability to interpret it.

It's still a good point, but it's a much more humble one.

> Whether I'm too ignorant to figure out from the source code how to
> fricassee, or the source code's so poorly written that most people can't
> figure it out, or the docs fail to explain it, or it just can't do that in
> the first place, the end result is the same: no fricassee-ing.

However, those are each very different problems with very different solutio=
ns.

If it's just you, then I should do what I can to give you the tools you nee=
d=20
to be able to figure it out yourself, should you need to. I've been trying =
to=20
do that here.

If it's really that poorly written, that absolutely is a good reason to use=
=20
something else.

If the docs don't explain it, and it's something that's supposed to be a=20
feature, the docs should be fixed. However, if the docs don't explain it=20
because it was never designed as a feature in the first place, but is just =
a=20
sort of accidental result of how it's designed, that suggests either it's f=
ine=20
the way it is, or it should be added as an official, public-API feature wit=
h=20
quality documentation.

In particular, documenting something generally makes it part of the public=
=20
API, which means people will be cross if you change it. (If it was document=
ed=20
but not public, it wouldn't be ideal for your purposes, anyway.)

In the last case, the feature should be added if it makes sense.

Now, the ideal steps for you in each of these cases is roughly the same: "I=
s=20
there a way to fricassee? I don't see it in the documentation, and I can't=
=20
figure it out..." or "It looks like I can fricassee this way. Is that likel=
y=20
to change in the future? If so, can I get an official public API for it?"

I don't know if you tried these. If you did and got no response, that's=20
certainly a failing of the community, and I apologize.

> I kept finding
> tutorials that would say "or you can edit the blahblah file to work with
> an existing legacy database." However, I couldn't even *get* a blahblah
> file to edit from either Rails or Ramaze,

Well, but which file? If it was schema.rb, I don't know that it would've=20
helped...

> Sinatra (or rather, the ORM that came bundled
> with Sinatra)

Which is that? I wasn't aware Sinatra came bundled with an ORM. I wasn't aw=
are=20
that it made sense for there to be -- seems like you'd just use an ORM=20
directly, without Sinatra knowing or caring about it.

> Should there be even
> more docs for people trying to use Sequel who've never worked directly
> with a SQL database before? It *would* make Sequel even more accessible to
> more programmers, but it's probably not worth the effort it would take for
> somebody to create that much more documentation.

Well, in that case, the idea would be to go elsewhere to learn SQL.

> I certainly don't see a clear
> path between a code fragment in a test suite to, I guess, embedding
> "Haml::Engine.new(@varWithMyHamlCodeInIt)" inside a Haml template. If you
> do, please do NOT tell me. I'm not using Haml, and at this point can't
> imagine any benefit I could derive that would pay back the cost of
> switching my existing code base over to it.

Sorry, I have to, because it's still a one-liner -- the result of that=20
'render' call seems like it'd be a string, like any other you might generat=
e,=20
and Haml doesn't escape strings unless you tell it to. The naive usage woul=
d=20
look like this:

=3D Haml::Engine.new(@var).render(self)

If I had doubts it'd be a string, I'd test it in IRB.

> But this, in the end, is all nit-picky detail.

Maybe, and I apologize if that's all it is. My point for getting into this =
was=20
to find out where the gap between my experience of things truly being easy=
=20
(even when starting out), and your experience of things being difficult or=
=20
impossible.

If it's something I can clear up here, that's helpful. If it's something=20
that's missing from the community as a whole, that's also good to know, too.

> like myself, his background and knowledge base were not the
> assumed default, and I believe that this was one of the reasons why he
> found the whole process so unexpectedly unproductive.

If that's really all it is, then I hope, if nothing else, I've helped bring=
=20
you closer to that.

=46rom where I'm standing, it looks like the pain point was going against t=
he=20
grain while also being a newbie. That's part of why I've beaten this Haml=20
horse to death -- the answer to the question of "How do I embed Haml code i=
nto=20
my controller?" is generally "Don't do that. Use partials instead." A ton o=
f=20
newbie questions reduce to something similar.

Unfortunately, we can't do that with all of your problems. For example, my=
=20
kneejerk reaction when I see people ask "How do I tie this to a legacy=20
schema?" is "Don't do that, migrate to something sane." But that's obviousl=
y=20
wrong.

=46or what it's worth, as badly as we might need better documentation and=20
tutorials for working with legacy databases, I found it even more frustrati=
ng=20
in the world of Oracle ADF, where an existing, legacy Oracle database=20
(complete with DBA) was assumed, and there was no easy, step-by-step guide =
on=20
getting from zero to a Hello World app.