Hacker News Reader

Comment by WalterBright | Hacker News Reader

I find it very helpful, when implementing part of the compiler, to include a link (for D) or a paragraph number (for C) that references the corresponding specification section:

https://github.com/dlang/dmd/blob/master/src/dmd/cparse.d#L5...

Ever since the Intel CPU spec went online, I started doing this with the code generator - providing links to the man page for the instruction being used:

https://github.com/dlang/dmd/blob/master/src/dmd/backend/cgx...

And for bug fixes, reference the issue which often gives a detailed explanation for why the code is a certain way:

https://github.com/dlang/dmd/blob/master/src/dmd/expressions...

Ever since I enhanced the editor I use to open the browser on links, this sort of thing has proven to be very, very handy.

View on HN

I've done the "reference the spec section" thing before -- the difficulty is that often section numbers or similar things get stale when a newer revision of the spec document is published; so it can work for a slow-moving thing like the C spec but is more awkward if the spec/manual gets a revision every six months.

It's a good point. This is why for C the references are to a specific standard, i.e. C11. For D, I use named links, which we try to not change. The bugzilla numbers do not change, which is a feature of bugzilla.

Even so, the utility of the links far outweighs the possibility of needing to adjust them.

P.S. I've found using links to Microsoft documentation to be extremely frustrating, because not only does Microsoft move them around all the time, but will wholesale permanently delete vast swaths of reference material.

Notice that the github links are to line numbers. Line numbers are ephemeral, I don't know a way around that.

One way I’ve found is to quote the thing I’m citing. Context and length dependent, of course. This also has the advantage of showing how the doc looked when you write the code, so the comment rots less slowly (and if something changes, you can see by comparing the excerpts)

I've considered that, but was concerned about copyright issues.

Interesting. IANAL but is saying “we have to do this dumb workaround because of xyz” criticism under (US) fair use?

You're probably right, but I don't want to deal with a lawyer on this. It's not worth it.

> Notice that the github links are to line numbers. Line numbers are ephemeral, I don't know a way around that.

If you go to your link, under the button with 3 dots there's a "copy permalink option" that creates a link to the specific commit you're looking at, ensuring the line number doesn't get out of date. Example:

https://github.com/dlang/dmd/blob/9003e2ae7e11faed433638e9cb...

Perfect! Thanks!

Looking at the code on GitHub, this extension may be useful: https://greasyfork.org/en/scripts/2709-linkify-plus

Not needed, I fixed my editor to automagically recognize URLs and make them clickable!

Reply on news.ycombinator.com