1

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?

3

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.

0

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.

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