Quinn Slack on November 1, 2016
What’s the best semantic and future-proof way to link to a piece of code? There's been some interesting discussion about the right way, and it’s something we think about a lot at Sourcegraph as we build a better way for developers to discover and understand code.
The consensus is that when you’re linking to a file, you should refer to a specific commit ID, not a branch or tag, so that the link works even if the file’s lines change. (On GitHub and Sourcegraph, you can change the URL to refer to an absolute commit ID by pressing “y”.)
But let’s take a step back. Linking to line numbers in code is useful when you want to point out a specific error or implementation technique: “Hey, check line 132 of app.go. You’re not closing the response body.”
Most of the time, though, you actually want to link to a specific definition by name:
Where do you think this leads?
In these cases, linking to the line number on GitHub means your link will quickly either become outdated (if you link to a branch) or will refer to an older version of the definition (if you link to a full commit ID).
Sourcegraph makes it possible to actually link to a definition with a URL for every function. These URLs always refer to the latest definition and won’t break if the file is edited, unlike links to a specific line number. You can also hack these URLs to quickly view other definitions (because the naming scheme is consistent and meaningful).
A semantic URL to fmt.Printf on Sourcegraph
These URLs also show other useful information about the definition: its type signature (with type inference for dynamic languages), usage examples, authors, users, etc. And you can link directly into source, as well:
The source code of a Go function, MarshalIndent, on Sourcegraph
Lots of open source projects already use these Sourcegraph URLs to refer to specific functions in their docs and bug trackers (Django, for example).
Here are some examples of named URLs:
To get the named URL to a function on Sourcegraph:
That’s it. You can also use the Sourcegraph Chrome extension to make it easy to jump to any function’s URL when you’re on GitHub.
To refer to a function at a specific point in time, you can add an explicit commit ID by pressing “y”.
There are a few problems with using named URLs, but they don’t prevent them from being useful today.
We’re working on improving these things and more.
Next time you need to link to code, link to it on Sourcegraph so your links refer to named definitions, not just files and lines. Here’s one to try first: func MarshalIndent.