Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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)

share|improve this question

migrated from stackoverflow.com Feb 3 '12 at 3:01

This question came from our site for professional and enthusiast programmers.

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. –  Tristan St. May 17 '10 at 16:44
6  
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). –  FrustratedWithFormsDesigner May 17 '10 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. –  Tristan St. May 17 '10 at 16:53
1  
Are you talking about code which you write for your team? Ask them. –  Aryabhatta May 19 '10 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 '12 at 9:21

5 Answers 5

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.

share|improve this answer

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.

share|improve this answer
1  
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 :) –  Tristan St. May 17 '10 at 16:51

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.

share|improve this answer
    
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)? –  Tristan St. May 17 '10 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 '10 at 17:25

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.

share|improve this answer

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.

share|improve this answer

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

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