Sometimes I think it's useful to cite a webpage (e.g. Stack Overflow questions) to justify and explain a piece of code. Is this considered bad practice?
Asked
Active
Viewed 1,163 times
3
-
http://meta.programmers.stackexchange.com/questions/6483/why-was-my-question-closed-or-down-voted/6491#6491 – gnat Mar 23 '14 at 14:58
-
If recreating the reference would make it massive: Hell yes. – Izkata Mar 23 '14 at 15:52
2 Answers
5
You may put URLs inside your comments, but consider the problems it might raise:
- No-one actually copies the link, and goes to read what the content of the URL actually say.
- The link/site might not be there a year in the future, or even next week
- You might forget to update the comment when the code below it changes, which will confuse a future reader even further.
I believe that you should not put URLs inside your comments unless you also paste the relevant quote from it, and then the URL is only used as a re-enforcement for the comment, or as in-depth further reading.
Uri Agassi
- 1,761
- 11
- 18
-
1Bullet 2 is why I try to only do this with StackOverflow, since we try to actively fight link rot here – Izkata Mar 23 '14 at 15:51
1
As long as you and your team are disciplined about comments, sure.
Use long-term reliable sites for your references:
a) wiki or other internal sites maintained by your team for the life of the project.
b) internal sites maintained by your organization that have a long-term maintenance agreement regarding preserving links.
c) external sites that have commitments to long-term maintenance of links. E.g., wikipedia, stack exchange, open source vendor sites, etc.
The alternatives to putting links into your comments are often worse.
1) Multiple maintenance: don't repeat yourself in an explanation of a coding instance, especially when it affects multiple pieces of source code.
2) Trying to summarize a board discussion when you've already implemented the code is frequently redundant.
BobDalgleish
- 4,694