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.
Is it a bad practice to cite URLs as references in comments? [closed]
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?
2
You may put URLs inside your comments, but consider the problems it might raise:
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.
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.
Filed under: softwareengineering - @ 08:29
Thẻ: comments
Is it a bad practice to cite URLs as references in comments? [closed]
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?
2
You may put URLs inside your comments, but consider the problems it might raise:
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.
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.
Filed under: softwareengineering - @ 08:29
Thẻ: comments
« Python – only one return per method? [duplicate] ⇐ More Pages ⇒ Is it a bad practice to cite URLs as references in comments? [closed] »