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...
> > 
> > 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.
> 
> I don't know why you hate to say that.

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

That's workable, but certainly not ideal. I hate to say it because I don't 
think people should have to dig into source code to get stuff done -- but it 
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.
> 
> I would agree with that.
> 
> 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 
took me almost no time to find, and it does make sense to me why it'd be that 
way. Specifically, it makes sense that you'd have a template object that 
represents some sort of "compiled" form of a template (or at least parsed 
form) so that you can efficiently combine that with a given environment (the 
self and locals arguments), rather than re-parsing the template on every 
request.

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

> 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 API. 
If you're hacking on the source, you get to keep both pieces when it breaks. 
It would be nice if there was better documentation as to where to get started, 
for people who do want to play with the source, but ultimately, if you're 
playing with the source, the goal should either be a fork or a patch, probably 
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 Ruby 
won't let me do this," or "I can't believe Ruby makes it so difficult to do 
this," to "I might have missed how to do this." One is a statement about the 
tool itself -- the language, the framework, or the community behind it -- and 
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 solutions.

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

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

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

In particular, documenting something generally makes it part of the public 
API, which means people will be cross if you change it. (If it was documented 
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: "Is 
there a way to fricassee? I don't see it in the documentation, and I can't 
figure it out..." or "It looks like I can fricassee this way. Is that likely 
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 
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 
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 aware 
that it made sense for there to be -- seems like you'd just use an ORM 
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 
'render' call seems like it'd be a string, like any other you might generate, 
and Haml doesn't escape strings unless you tell it to. The naive usage would 
look like this:

= 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 
to find out where the gap between my experience of things truly being easy 
(even when starting out), and your experience of things being difficult or 
impossible.

If it's something I can clear up here, that's helpful. If it's something 
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 
you closer to that.

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

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

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