Is it OK to put a link to Q&A sites in a program's comments?

Question

In quite some codebase you can see comments stating things like:

 // Workaround for defect 'xxx', (See bug 1434594 on Sun's bugparade)

So I've got a few questions, but they're all related.

Is it OK to put link to SO questions in a program's comments:

 // We're now mapping from the "sorted-on column" to original indices.
 //
 // There's apparently no easy way to do this in Java, so we're
 // re-inventing a wheel.
 //
 // (see why here, in SO question: http://stackoverflow.com/questions/951848)

Do you do it?

And what are the drawbacks in doing so? (see my first comment for a terrible drawback)

Answer 1

Ideally your code needs no such comments because it's well structured, etc. But yes, when your situation is less than ideal, it's acceptable to put in comments like this. And links to stackoverflow.com are as good (and often better!) than others.

Hopefully they're temporary comments, and you'll be allowed to come back and improve the code and take these comments out.

I have not yet put a StackOverflow.com link in my code. I try to avoid putting links in code, since it's a bad smell, but when the time comes I won't hesitate.

Edit: I think my above answer gives the impression that the need for comments such as this is avoidable. Of course sometimes it's not avoidable; it's a bug in a library or poor API design that you have no control over. Comments like this, including links, is very helpful for the next developer to come along.

Answer 2

Generally, the best way to create this link is through the versionning system and/or the bug tracking system. The requirement for this to work though is that you can accurately link your code to the bug tracker or the place in the versionning system where you put your comments.

Answer 3

I've done it, maybe not specifically for Stack Overflow, but for technical blogs, forums, Usenet, Google Groups, or any other places where the "why did I do this" may not be completely clear from the context.

I don't see why using SO like this would be a bad thing, unless they archive and purge off old questions (which I don't think they do, but I'm not sure) - but even if they do, it's no worse than any other site.

If you're really worried about that, you can always take screenshots or download these pages as text (or go through the trouble of getting the images, stylesheets, etc.), and saving them to a knowledge repository at your company, attaching a unique identifier to it, and putting that unique identifier in your comments to allow you to reference later - then you'd have a consistent place for this type of thing. But that may be overkill, depending on the complexity and importance of your code.