What is meta? ×
Meta Stack Exchange is where users like you discuss bugs, features, and support issues that affect the software powering all 133 Stack Exchange communities.

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 May 17 '10 at 16:54

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

8  
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. –  OldEnthusiast May 17 '10 at 16:44
3  
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
    
I second that. What, if SO decides to close? Then the comment is worthless. –  Sebastian P.R. Gingter May 17 '10 at 16:48
    
@FrustratedWithFormsDesigner: +1 to your comment... Putting a clear and concise summary of the SO question and answer is indeed a good idea. My question is really to get feedback/see how fellow SO users deal with this issue (if any at all :) –  OldEnthusiast May 17 '10 at 16:49
1  
Not a bad question, but belongs on meta. –  Robert S. May 17 '10 at 16:50
4  
@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. –  OldEnthusiast May 17 '10 at 16:53
    
please vote to migrate back to SO, this is not a meta at all. I'm not criticizing nor disputing at all the way SO works: this is a question from a programmer's point of view and there are already several SOer answering it. This has nothing to do with a meta. –  OldEnthusiast May 17 '10 at 16:57
7  
This doesn't not belong on meta! This is about what to do in your code. This is a very legitimate question, and is not about using stackoverflow.com. It's about commenting code. I don't have the rep here on stackoverflow to move it back. Can some people please put this back on stackoverflow.com, where it belongs? –  Patrick Karcher May 17 '10 at 16:57
1  
@OldEnthusiast @Patrick: No, they cannot. Migrating out of Meta is not currently supported: meta.stackoverflow.com/questions/12039/… –  Pops May 17 '10 at 17:07
1  
Flag either this or the original question for moderator attention. Explain the problem (or refer to the comments). A mod should be able to delete this question and restore the original. –  ChrisF May 17 '10 at 17:46
1  
If/when this gets reopened on SO (I support that), I think the title should be edited so that it doesn't appear that you're asking "are you allowed to ..." when you're really asking "is it a good idea to ..." -- that's probably why it got migrated here in the first place. –  Jon Seigel May 17 '10 at 18:00

4 Answers 4

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 I gave the impression above that you can avoid needing such unfortunate comments by being a good coder and having enough time. There are many times though where such comments are needed by something completely outside your control. Comments such as this can be a godsend to the poor developer who has to work with this code a year from now.

share|improve this answer
    
@Patrick Karcher: 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 :) –  OldEnthusiast 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
    
@Loki: 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)? –  OldEnthusiast May 17 '10 at 16:53

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

Personally I would rather want to avoid it. When you, for whatever reason, adapt a solution posted here (or anywhere else) for your actual productive code, you should rather understand the actual solution, and write it yourself again (that way you can be sure that you did get it). If necessary you can then add a short explanation, again written by yourself, to it, to make the solution clear to others as well.

But when you just use SO as source for code parts or solutions, there is a high possibility that you don't really understand the code yourself. And sooner or later this will lead to further problems, not only if you don't understand it again when you read the code later, but also when other programmers see your code and have a question.

share|improve this answer

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .