Comment by mgkimsal | Hacker News Reader

Comment by mgkimsal | Hacker News Reader

Parent Full thread

"Beyond the fact that you will most likely find exactly the answer you are looking for, there are some other side effects."

That's either naive, or only looking at simple libraries, or has the luxury of taking as much time as necessary to dig/poke around, absorbing multiple author styles. My head starts to hurt after looking at often un- or poorly-documented libraries written in a mishmash of styles.

I often search first - google/irc/bing/mailinglists, etc - because I'll find out pretty quickly if other people are really using the library. They'll have found and dealt with the real world issues that come up (the docs say X, but really, you should do Y, because of performance, security, etc). If no one is using something, perhaps there's a reason - searching will turn that up.

Finding an error message like "Foobar is barfoo-ed on line X", then having to trace through back from line X through 30 calls, then finding that all I see is a sprintf() error message of "%s is %s" doesn't really help. Yay - I read the code! It's not useful/helpful in debugging my real world use of your library, not the few aspects you felt like documenting or commenting.

Looking at code and docs alone only solves my issues about 25% of the time - maybe up to 50% depending on the platform/problem domain. I guess all is magical in the Ruby/Rails world - 100% of all problems are solvable solely by looking at the purity that is all Ruby code, apparently.

You don't have to understand the library, the author's coding style, or even much of the language in order to answer a question like this. You grep the codebase for '302' to find the constant that represents a redirect, and then you grep for that constant. 90% of the time, that should take you right to the chunk of code you're interested in.

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.

> everyone else's code is hard to read

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.

Perhaps for debugging reading code isn't that useful. But when determining whether a certain feature is or isn't supported, if Google comes up empty reading the code seems like the natural choice.

Reply on news.ycombinator.com