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.
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
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 :)
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.
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.
I mean, even with web frameworks you could take this to the next level. Want to know how a bit of CSS works? Don't read the HTML5 docs--- just dig right into the Firefox and Chromium codebases to see what browsers actually do with it.
Anyway, I used to work like this, but a couple years ago I just said "screw it" and started diving in and reading the source for libraries that I use. And that's been a very good decision so far. Using only libraries that are well-documented sets a ceiling on what you can accomplish, and hence makes your software less impressive and your potential rewards much lower. Everybody else can Google the web and read the docs; relatively few people are willing to dive into the source and understand how the library really works. The way to distinguish yourself from those people is to do what they're not willing to, and work on the hard stuff.
Some libraries are poorly documented because their authors are lazy, but many more are poorly documented because their authors are working on hard problems. If you leverage their work, even though it's not easy, you can work on hard problems too, and that's where most of the rewards are.
I'm currently doing a lot of stuff with LLVM. LLVM is actually fairly well-documented for an open-source project: there's at least a bunch of tutorials and Doxygen. Despite this, there've still been a bunch of times I've had to go back to the source. I had to hunt around to figure out how to disable the default dlsym() behavior and explicitly expose all functions I want the compiled code to be able to access. And then I found this didn't work when I statically linked the binary; I had to ask a coworker who's a dev on the project what was up, and it turned out it was a bug in the compiler framework.
For my startup, I was doing a bunch with mtasc and swfmill. Beyond basic command-line options, there's pretty much no reference for how to put these together to generate a Flash file of moderate complexity. I basically just tried things that sorta looked like the demo examples, and permuted them until they worked.
A few years back, I did a bunch with Netbeans. I had to look at the source code for virtually everything. I had to manually trace back deadlocks by seeing which framework code was holding which monitors. I had to grep the codebase to figure out which Lookup file a particular extension point was checking. Most of the APIs, I just had to try and see whether they did with I want.
Usually, the only open-source libraries that work smoothly are the ones that lots of people are already using. They got that way because the early adopters put up with a bunch of pain and contributed back to fixing the problems they encountered. If you're fine with trailing the pack, you can rely on the documentation. But if you're going to lead the pack, you often have to write the documentation.
Seriously, a 'library' can be anything, from a standard, well document library that comes with the OS, to a chunk of code you got from a coworker. No all of them will have documentation, and then even if you have it it's often the case that the documentation is not 100% correct or up to date.
I did this yesterday. The README of Authlogic doesn't cover using a single access token to log in without a username or password, but the comments in the code does:
Okay, check out Params:
If you know the basic principles of programming then you can always just search for 'how do I _____ in ______' and get your answer quickly.
Very true, however this only works for languages that are just like the languages you already know. So taking a mythical enterprise programmer (no hate mail, please!), he can google for "How do I implement a for loop in Scheme" and get an answer, but of course he may entirely miss the fact that tail recursion is optimized by default and that the idiomatic way to solve his problem would be to write a recursive function.
For this reason, I hope that when Googling things, people take the extra step of just plain reading words. Lots of words. Blog posts, books (online or dead trees), rants in forums, everything.
The limitation of asking a question (whether in Google or StackOverflow or whatever) is that when learning a new way to think about programming, you don't know what question to ask.
The best way in my view to learn those related things is usually in a good book about the subject. I fail to see blogs/stack overflow/google ever beating a good book about a subject.
Doing this, I accumulated a pretty large collection of (mainly O'Reilly) books.
Now, you just do a Google search for a topic, and you're flooded with examples and people explaining how to do X in Y. My book collection stopped growing in about 2003.
That's not even covering error messages and APIs... being able to Google a specific error message is wonderful. And I couldn't imagine coding again without immediate access to the language APIs online.
I agree with the side-benefits of reading code, but accessing the strength of the library is more efficiently done by its documentation and community and not directly by source.
Example: How many people would use Linux without the man pages?
But, a lot of programmers I know, don't look at the code for some reason, they just search and search on google, then go to irc to ask around and waste a lot of time when they could have found their answer in 5 minutes...
"Less google! More grep!"
That means when I search a part number it turns up a pop cd by serial number, when I ask for information on a scientific subject I get a 6 year old yahoo answers post, etc.
I realize now that, in the past, the most value I extracted from Google was finding good resources to refer to again in the future.
I've been considering writing a tool that, upon being queried, figures out 6-12 of the best resources available and googles within them for that query. Kind of the "Yahoo of Google" (back when yahoo was a directory based system)
They will threat anything not written by them as a blackbox and if it's not working they will poke around it endlessly, they will do anything but walk through the code and find the root issue.
"Here is hoping this article lights some peeps on fire instead of lighting a fire for them."
Definitely a good fire to start.
How do we learn them? Two ways. (1) spend time on our own. This can either be brute force (i.e. just exploring every folder over several projects until a pattern emerges) or though a guided tutorial. (2) Ask someone with more experience.
As for as (2) goes, when someone asks me a question that I think is trivial, I try to realize that its not trivial to them. This person is asking because they respect my ideas and they think I can save them a good deal of time.
I don't hold everyone's hand though. Sometimes I do respond with "consider searching for X and trying Y on your own". Where the appropriate line lies for direct answers versus gentle encouragement, I do not know. However, politeness, in both cases, is free.
This way when you're looking at, say, the Request objects :remote_ip method, one click gets you to the implementation along with the ability to follow the code around the Class.
And since the code for it's available as a standalone (http://github.com/voloko/sdoc/), your not limited to just the Rails docs, but any ruby code on Github.
I was looking for a simple Python webserver on which to do some Comet stuff a few months ago, and despite some fairly limited documentation, reading the code made it obvious how to use Tornado and that it was a straightforward, well-architected solution to the problem I had. Whereas Twisted was a disaster that I did not want to get anywhere near.
"Don't stop when googling turns up nothing"
Googling for info is near optimal, it should not be abandoned. Sadly, I can get an answer from google quicker than I can from coworker.
"So how would I have approached my dudes problem? [8 step list follows]
How his friend tried to solve the provlem? [1 step list]
Following this line of thought to its logical conclusion, if everyone thought thing was such a bad thing, Hacker News would likely not even exist. Sharing knowledge is what the internet does best.
(Disclaimer: I'm not advocating never reading source code, I do it all the time for topics I truly want/need a deeper level of understanding on, but for the rest of the time…)
The answer to specific programming questions always lies in the code. If everyone looked at the code first, our software would be 100x better than it is now. (More eyes, more shared experience.)
(Unless it's a feature request, I suppose)
The only thing to keep in note is that google isn't a necessary condition. Not seeing a google result means you might want to try investigating further, not that you want to get yelled at by this dude.
(Not trolling, there is an acknowledged lack of documentation for MongoMapper; I'm just poking fun at John)
that's probably a sign that you don't want to use that code especially if YOU can't understand what the hell it's doing.
I tend to look at tests first more often then dive into the actual code.
The rest is up to the dev using the library. Use it as a black box, grey box or clear box - it's your choice and your risk.