16

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)

9
  • 9
    commenting to myself: one very concerning drawback when doing that is that due to the fact that SO is a Wiki there's exactly zero guarantee that the answer(s) you rely on will still be correct (or even still be there). Heck, in some cases the question itself could be closed or changed from its original meaning. The huge difference between "See bug 1434594" on Sun's bug parade is that you're guaranteed that the text from Sun's bug link shall not ("shall not" as in defined by RFC2119) change. This is huge: the fact that SO is a wiki makes me nervous putting SO links in comments. May 17, 2010 at 16:44
  • 7
    Your best bet is to put a clear and concise summary of the SO answer, and then put the reference link underneath that. I've done that on several occasions. That way, if SO ever goes under or the answer is removed/edited, the core information you wanted is still in your summary. Now, depending on the complexity of the answer, writing the summary could be a whole separate chore. If the SO answer links to something else, might be worth it to link to those to (especially if they are less ephemeral than SO answers). May 17, 2010 at 16:47
  • 5
    @Robert S.: no, it's not a meta. It's not about SO: I'm accepting SO the way it is. This is specifically about how to deal with a SO-like resource from a comment. May 17, 2010 at 16:53
  • 1
    Are you talking about code which you write for your team? Ask them.
    – Aryabhatta
    May 19, 2010 at 20:47
  • 1
    You can always save the whole web page as a complete web page, zip it and put it in your documentary folder.
    – user1249
    Feb 3, 2012 at 9:21

5 Answers 5

7

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.

5

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.

2
  • that's interesting: so you're actually suggesting that in the case of an SO answer I could fetch the HTML and store it in my DVCS (Mercurial but that's not the point)? May 17, 2010 at 16:53
  • Well, normally you don't need the whole thing, just the relevant bits right? And you can reference the source.
    – Loki
    May 20, 2010 at 17:25
5

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.

1
  • 2
    hey, look at that one, I wish there would a "cleaner" way to deal with it, but very often it's not the case stackoverflow.com/questions/951848 I mean, bugs and inconsistencies/weird API, undocumented behavior, etc. are part of our programmer lifes :) May 17, 2010 at 16:51
2

I view it like writing a research paper. If I use someone else's ideas, then I need to give credit for those ideas. I have used an answer from stackoverflow in my code before, and I added the link to the comments of method.

As someone mentioned, SO is a wiki style, so it's possible that it could change, but generally the idea should still be the same.

You should still give credit to others when you use their ideas.

1

If you have needed to implement a work-around, and it is not obvious why the implementation was done a particular way, then a comment really should be let to identify the reasons why. I think placing a link to an online reference is fine, but you really need to have made your comment succinct, yet complete enough that the link will only provide an expanded explanation should the reader feel a need to double check your reasoning.

If on the other hand the code has been copied verbatim, then a link to the original source is only fair, and may be required depending on the wording of the license under which you have been allowed to copy the original author's work.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.