I initially disagreed, but the actual quote is better: "The right example is worth a thousand lines of documentation."
There are many cases where explaining things is better, and a well-crafted explanation with a few sparing examples is often the best way to communicate an idea — but there are some cases where a particular example is clearer than any explanation could hope to be.
"But they didn't go through and parse the code like we do. It couldn't tell you who else uses this particular function or repository."
It may have, but perhaps didn't present the UI for external users. Our internal version of Codesearch based on Grok (http://www.stanford.edu/class/ee380/Abstracts/121010.html) is far more powerful and works just like an advanced IDE -> find usages, callers, implementors, overrides, all kinds of auditing/analysis layers too.
Some Googlers practically live in Codesearch rather than use the local IDE indexing :)
As someone stuck with CScope on Linux, I really really wish there were better alternatives for the wider world. (required features: works with C, query from terminal as well as from IDE (inc. Vim/Emacs), possibility to jump to func/type definition as well as callers/users)
Codesearch is probably the largest reason I am jealous of my friends at Google.
Really cool looking site, but I'm not entirely sure how to use it! I went to the site used one of the suggested searches (djano Charfield). A lot of the search results actually brought me to a 404 page (confusing?). Even then, since most of the examples listed were classes, I'm not entirely sure how this relates to "a single example...", as these weren't examples?
At the end of the day I love Javadocs though - I really feel like I get the best understanding from them because of ability to easily browse packages, go up and down inheritance hierarchy, see all implementing classes, and there are typically some good examples in it too.
For me this really depends on the examples. I tried learning Haskell years ago and the examples I found were confounding. Reading through documentation and books on the language was much more helpful. Unfortunately, I still suck at Haskell.
I find most the examples I need in Stackoverflow, along with community ratings and comments.
Which reminds me of another idea which I think I remember Jeff Attwood talking about: We all copy these snippets from websites into our code. Those snippets might have bugs that are later fixed by others on the web, or the APIs change or get deprecated, etc. It would be good to have a reference from the code to the web page so in the future you can remember where that snippet came from and look it up and maybe see if the community's recommendations have changed. But even better would be if the bugs that were fixed by the web-community ended up back in your code automatically. So imagine Stackoverflow with a gist-type comment system for the code snippets with versioning and community editing, and then you could somehow do a pull on those gists and grab the community's wisdom automatically.
Do people really copy snippets they found on a website into their code? I use examples on the web to further my understanding of a technical issue but would never cut and paste blocks of code. Aside from the copyright uncertainty, I simply wouldn't trust a piece of random code found on the web enough to pull it into my own.
That said, I do agree that if you've make choices in your code based on information that you found online, its good to include a reference to the source in a comment.
My only question is: why do they spawn git/hg processes? Why not use http://libgit2.github.com/ (git) and some other library for Mercurial instead? That way you're not spawning and killing off processes, you just send data from a library
Yep, that's one of the improvements we're working on. We made a lib that wraps libgit2 (git2go) and knierem/hgo at https://github.com/sourcegraph/go-vcs that we'll push to our live site soon. Initially we shelled out to git/hg for simplicity.
Not just Apache, Nginx frequently has this problem as well. A decently written bit of documention on how a module is supposed to work and what it does, but very unclear on how the syntax is actually meant to be written.
I agree. I think the difference is the sequence you do it in. For me, it is so much easier to get the code and look at it and step through it, THEN read the documentation. This approach helps me to focus on the parts that are unfamiliar, which I will research in more depth. At some point, you do need to read the documentation. Just not necessarily monolithically before you start experimenting with the code.
I write ruby code. I have used snippets that I didn't fully understand. It turn out in the usual way "it works but I don't understand exactly how...". I ended with simpler code that I understand, was able to write test and all by reading the documentation.
Co-creator of Sourcegraph here. Just FYI, in addition to usage examples, we also display the documentation and fully-linked source code (so you can jump to definition, etc.)
Sometimes the documentation tells you exactly what you need. Sometimes you want an at-a-glance example. And sometimes you might want to dive into the source to figure out what's going on. Whatever it is you're doing to understand a piece of code, we want to make it as easy as possible.
I'm extremely interested to see how Sourcegraph continues to define "right example" down the road. Collaborative filtering and more powerful heuristics both spring to mind as possible options.
There are many cases where explaining things is better, and a well-crafted explanation with a few sparing examples is often the best way to communicate an idea — but there are some cases where a particular example is clearer than any explanation could hope to be.