
Sourcegraph: "A single example is worth 1000 lines of documentation" - mallyvai
http://codeinsider.us/i/4.html
======
chc
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.

~~~
collyw
Decent documentation should include an example.

------
cromwellian
"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](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 :)

~~~
AceJohnny2
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.

~~~
justinmk
> As someone stuck with CScope on Linux, I really really wish there were
> better alternatives

Doesn't clang (using a frontend like YCM[1]) provide exactly that?

[1]
[https://github.com/Valloric/YouCompleteMe](https://github.com/Valloric/YouCompleteMe)

~~~
AceJohnny2
I didn't know about this! Looks like there's some experimental support for
Emacs out there... Thanks!

------
potatosareok
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.

------
dopamean
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.

------
guelo
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.

~~~
bostonpete
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.

------
striking
My only question is: why do they spawn git/hg processes? Why not use
[http://libgit2.github.com/](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

~~~
sqs
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](https://github.com/sourcegraph/go-vcs) that we'll push to our live site
soon. Initially we shelled out to git/hg for simplicity.

------
conjecTech
Examples and documentation are not substitutes in my mind. If you want your
work to be used, you need both.

------
jabwork
For RoR's method_missing give me the docs

For apache configuration, give me the examples!

I really like the use case of helping upstream maintainers decide on method
deprecation/adding helper functions. Fantastic idea

~~~
adwf
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.

------
gman129
Examples usually show you how do things like a parrot, but you don't get the
idea of why these things happen as they do without some documentation.

~~~
daphneokeefe
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.

------
atmosx
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.

Depends on the example, as other users said.

~~~
beliu
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.

~~~
atmosx
Then I guess it's the whole package :-)

You're right, some times a code sample might make things clearer, especially
for newbies.

------
mallyvai
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.

------
zobzu
Just put a good example WITH the doc. Thats.. how its done :)

