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

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=20
> decent test suite, which is always a good place to look when you want =
to know=20
> how to use some code.=20

I don't know why you hate to say that.=20

> But the point is, while good docs are a good thing, I think working =
and=20
> readable code is at least as important.

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?

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?"

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.=20

"I couldn't make the Frobulator fricassee."
"Oh, the Frobulator can definitely fricassee."
"I couldn't find any information about it in the documentation."
"Well, it's not in the documentation as such, unless you already know =
that fricassee is just a special case of fricolating a tri-fold array.  =
But it's easy to find in the source code."
"I haven't been able to figure out how this code works."

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.=20

I could tell pretty early on that my biggest problem with finding a good =
ORM was not that there were very few that were *capable* of doing what I =
wanted, but that very few of the people who'd written the documentation =
were describing their ORM's capabilities from the point of view that I =
had: from the database, instead of from the middleware. 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, because all the tutorials and =
documentation took it for granted that I was interested in making a new =
web site from scratch, and didn't really care all that much about the =
details of data storage.=20
	Sinatra (or rather, the ORM that came bundled with Sinatra) had =
a tool that was supposed to build me a class/object ORM file from my =
schema, but it couldn't handle UUID primary keys, so it only created =
about 33% of the material I needed.
	I then had to decide if it would be more efficient to just walk =
through the whole tutorial, learning about scaffolding and migrations, =
knowing that I would not have any use whatsoever for knowledge related =
to migrations, until I finally knew enough about the whole system that I =
would have the background needed to understand the code well enough to =
be able to figure out how to make it do what I wanted, OR would it be a =
better use of my time to start over with some other ORM or library or =
whatever, where I would be able to get started sooner by being able to =
take better advantage of my existing knowledge? I chose the latter =
route, although I would not be able to prove to somebody if it was the =
better choice or not.=20

The better I get at reading other people's Ruby code, the less I'll need =
to rely on good documentation.=20
There is a nebulous point of diminishing returns, where "better" (aka =
"more) documentation becomes a waste of time; there is a certain amount =
of knowledge that the user/programmer can be expected to know. For =
example, the Sequel documentation takes it for granted that I am totally =
familiar with SQL; most of the docs explain what the code does in terms =
of the equivalent SQL code. 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.=20

Certainly my inability to get Haml to work for me does not mean that its =
documentation sucks, or that it sucks. It just didn't work for me.=20


>  It took me about three minutes to find this:
>=20
> http://github.com/nex3/haml/blob/master/test/haml/template_test.rb
>=20
> In particular, this line:
>=20
> Haml::Engine.new(File.read(File.join(TemplateTest::TEMPLATE_PATH,=20
> "_#{name}.haml"))).render(self, locals)
>=20
> Seems to me that you'd just replace the "File.read" part with the =
source of=20
> whatever you're trying to render. Note that this will likely be _much_ =
more=20
> efficient if you can keep the Engine object around, and that's true =
for any=20
> template system, which is probably why it makes more sense for you to =
take=20
> whatever you were going to do here and put it in a partial...

Honestly, I have no idea what you just said. 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.=20

But this, in the end, is all nit-picky detail. My original discussion =
was all about how the current cacophony of Ruby-based middleware was =
actually quite cool and powerful, but that the original poster's to make =
something that is so often described as "really easy" to work at all was =
not some giant Ruby conspiracy or a massive delusion on our part, but =
reflected the fact that, 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.=20