At the risk of being seen as a rails douche, my response is that there is a strong culture in ruby and rails on authoring styles so it is not as painful. Beyond that, I am not saying that 100% of your problems are solved just looking at code. What I was trying to point out is that reading code is important and often times the answer. Google should not be your own tool. Hope that clarifies! :)
I've written plenty of Rails code, and I don't know where you find these well-documented libraries that are magically readable. Most Rails libraries are as abysmally documented as any other project.
Yeah, I'd have to agree. If we're going to say "there's a language that is more readable than others", then I guess Python's enforced "one way to do it" paradigm lends itself better to external eyes than Ruby does.
I guess Lisp'ers might feel similarly.
But it's all relative, everyone else's code is hard to read, at least for the first 15 minutes. By that time, you could have Googled 30 times over looking for the result.
I agree, and that could easily be "everyone's code is hard to read". Sometimes I look at some stuff I wrote a few years back and want to smack the author for writing such crappy code
He didn't say libs were well documented. He said ruby libraries usually have the same or similar structure/coding style.
The point is that it's oftentimes easier to grep the source for something than to track down said thing in google.
SPECIALLY because ruby libs tend to be horribly documented, but most times with simple-ish code to understand.
And, moreover, if you see a library that does too many weird things and you can't follow, it means that probably the code is shit and it's time to look for an alternative :)
I found Rails-related code much more painful to read than, erm, most other things I read. Smartassery, lack of documentation, and a language that gives you enough rope to shoot yourself in the foot are not a good combination.
Of course, the fact that the only sources of information about a library are “reading the code” and “googling” means that something has gone horribly wrong.
Honestly, I see this attitude manifest in a really nasty way in MongoMapper, which is an otherwise great library. If I would have realized that the documentation would still be non existant (like, completely non existent) after 10 months or so of using it I would have gone with Mongoid instead. Now my project is far enough along and I'm familiar enough with MM that it's just not worth it to switch now.
I'm a very competent developer and often have to sift through the MM source code to find what I'm looking for (or jump to the plucky source code). This is for doing things like finding the appropriate place to use #fields, stuff that _should_ be documented.
Every time I want to look something up I have to sift through the google group or grep through your source code, it's not that I'm not capable, it's just that it's a lousy way to work. Now, I realize that it's your project and you can do whatever you please, I'm just saying that I would have made a different descision and I'm sure the lack of documentation hurts MM uptake pretty severely.
It's funny you bring this up, because just yesterday I was using HTTParty and was getting strange errors when I was doing POSTs / PUT queries (basically the REST API I was using was giving me 500s and I didn't know why). After looking at your source, I then immediately realized I had to use the :body param instead of the :query param to pass in www-urlencoded values. Whether that reflects on the consistency or documentation of the API is another matter, but it just proves your point about the importance of being able to grok code.
