"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.
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.
I'm sure I'll be in the minority here, but a huge benefit of using libraries is that I don't have to know how they work, or care. The documentation says 'call foo() with this argument to do bar', and that's all I want to care about.
I have other things to worry about (like my own code), than to want to dig into the internals of somebody's else's library to figure out something which should be easily documented.
I see the benefit of a library as being that I don't need to write the code, but it still won't go in one of my projects until I understand what it does and whether it actually works the way it should. Personally, I encounter bugs and bad code in libraries all the time, especially in libraries that extend or hook into web frameworks.
I could see that working in web frameworks, where the library code is often doing something vaguely similar to the application code. I'm not sure how well it translates out of that scene, though. Am I really supposed to be reading the GNU libc source in order to debug my problem? Or the LAPACK source? It can occasionally help, but much of the time it won't. Do you really understand how all those libraries operate? Should you have to?
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.
Ironically, LAPACK is for the most part pretty straight forward. Most of the code is simply shells out to BLAS routines. Because everything is matrix-matrix, it all maps reasonably well to how you'd explain it in a math textbook.
Also, the documentation tells you what is intended to be public, stable API, vs. what's an implementation detail that may change with the next release.
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.
The trouble is that this behavior swaps over. I often see people on IRC googled for an answer, but would have never thought about looking at the nice, shipped, and even installed documentation.
I definitely feel the opposite. While there is a lot of crappy code out there, if you look, you can also find a lot of good code, which you can learn from.
Ruby code usually has the rdoc-style comments right above the method definition, and not all of those explanations make it to the README...
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:
Love authlogic; it's such a well-constructed library. Just the other day I borrowed the method they use for getting access to controller functionality like cookies and params. It's the sort of thing I've always done by passing the controller object to the method that needs it, but the authlogic way is just so much cleaner: http://github.com/binarylogic/authlogic/blob/master/lib/auth...
I didn't start programming until Google was in full swing - what I'd like to know is how much Google search 'changed the game' for learning programming languages. If you know the basic principles of programming then you can always just search for 'how do I _____ in ______' and get your answer quickly. Before the Google age, I suppose you'd have to read documentation much more thoroughly and build up fluency in order to get anything done. Has Google search and other web resources changed daily programming drastically?
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.
That extremely true, which is why I recommend not learning by Google as a default. Knowing what question to ask implies knowing things that relate to the issue.
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.
I grew up with 'learn by Googling' as my most used educational tool. It would have been wonderful if it didn't take so much time to sift through the endless misinformation, but doing so really leads to a pretty deep coverage of a topic. "Learning by Google" also often meant "Learning by perldoc" by proxy, or "Learning by O'Reilly e-books", etc. The real difficulty comes to when a subject is obscured by prominent shitty resourcess (Google, please blacklist w3schools.com, and please make the ACTUAL SPECS always turn up as the first result).
I'm not sure it was Google as much as the web in general (+Google). When I started coding in the mid 90's, if there was a topic I wanted to learn about, I needed to find a book about it. From there, I could walk though the book, skip the parts I already knew, and after reading the examples in the book, I'd have a pretty good idea and I could go off and write my code.
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.
Sorry, but if the library doesn't provide documentation as to the functionality it provides that can be indexed by Google, I'm not using it. I don't have time to go through code-bases with differing organizations, styles, and sometimes multiple languages and layers just to find out if it has feature x and how to configure it.
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.
Perhaps I'm old school, but I view undocumented functionality as something that may not always be there or behave the same in future releases. While I can deal with that since it's open source, it doesn't mean I want to. Libraries with good documentation are frequently much safer bets, and I've found good documentation is a great indicator of the maturity and stability of the project.
Example: How many people would use Linux without the man pages?
I'm not sure how you can really test w/o documentation. How do I know the test is testing the correct thing w/o the docs? I'm almost more worried about code with unit tests, but not docs, as I suspect a developer who just attended the latest "Cool Coding Trends Camp", rather than someone who has built and maintained a lot of code.
There is a cultural reason for googling instead of looking at the source: a lot of developers started programming for closed platforms like Windows or Mac OS, where looking at the source was not an option. In the same way, if you are accustomed to heavy frameworks like the ones released by Microsoft / Sun / Oracle, you don't seriously consider writing your own instead of waiting for their next latest-and-greatest tech release that is supposed to solve all your problems.
Exactly. Except I would not use inflammatory as the word. More I use titles like that to get people to read something that might not have, not to anger them. :)
Ah, that's a pet peeve of mine... I've always loved looking at the guts of any library I use, first because I often learn something new, second, because otherwise how can I rely on it?
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...
Personally, there are very few experiences I find more miserable than looking at other people's code. I'm sure other people feel the same way about my code. If I were in this position, I would probably start by looking at the documentation. If the feature I needed was in the code, but not in the documentation, I wouldn't want to use it.
Another aspect: People who don't dig into their libraries are much less likely to submit patches fixing minor issues they find. Quick digging through the source tells me a lot about a library - whether or not it can do something, if it's a horrible mess and should not be trusted in the first place, etc.
Google used to be "the search engine for smart people".
Now, as it is the de facto standard, it is "the search engine for everyone".
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)
Speaks a lot about the Ruby community that the answer here is not "rtfm". Typically there ISN'T a 'fm' to be found, and who knows how the code's getting monkeypatched, even by the library itself. So no, I don't trust that because I read the subset of code re: the thing that I care about that I fully understand the ramifications. I'm also guessing that the OP gets paid by the hour.
I completely agree with this article. I'm amazed at the self helpless of some programmers. I see people going to great lengths to try to find problems when there's a more direct route available.
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.
Guilty as charged. As a self-taught code tinkerer, Googling has become a major crutch, and I've found time and time again that Google just doesn't have basic answers that learning how to quickly scan the actual code can provide.
"Here is hoping this article lights some peeps on fire instead of lighting a fire for them."
I do not think any of us are born with the ability to understand the structure of GitHub and Rails projects. These are learned abilities.
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 is what I like about http://railsapi.com (which is just Sdoc), it gives you searchable ruby docs, and each method comes with a link to the code on Github.
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.
"... you will quickly get a feeling for how the project is organized (or not organized). This helps determine if you really still want to use this project."
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.
"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…)
It's strange -- I have never used Google for programming questions. When I was learning, Google didn't exist; I had to read a book or figure it out myself. Now, Google never has the answer to my question, so I'm again forced to figure it out myself.
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.)
No matter how much you agree with the author's opinion, Googling has the strong benefit of being a fast sufficiency condition. If you see a google result about your feature, you can be 99% sure the feature exists.
(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.
From my experience, reading code is a super important skill that just isn't taught in colleges. Just as reading and writing English (Or any other language) are separate but related skills, so too reading and writing code are separate but related skills. If you have a hard time reading other people's code, go practice. Learning to read code was one of the more enlightening experiences I've had as a programmer.
The problem I've seen with some junior developers is not that they run to Google it's that they aren't very proficient at using it. On a number of occasions in the last couple of months I've had a junior dev stuck on a problem for hours. On each occasion I sat down with them and once I understood the problem went and did my own googling and cam up with the answer in five minutes.
It seems to me the worse problem is those who come across a problem like this and just assume it will not work without searching for the solution OR looking at the code. It should be obvious to any developer that both methods of solving your problem are useful.
Google Code Search anybody? If the answer can be gleaned from source code, you can still Google it. I use GCS often to look for examples of using a particular library or function.
You should know how to use and use all tools, incl. google, bing, ddg, github, Ctrl-F7 with searching with in text, etc. Google - is just another search tool.
Why is this article about reading code and knowing what library you're getting yourself into titled "Stop Googling". The title is hardly fitting and the rant about not Googling things is just common sense and isn't worthy of a post.
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.
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.