9

Often I find myself solving bugs by finding the answer on Stack Overflow. Is it bad practice to add a snippet of why I did what I did and then add a link to an article or page from the web?

Improve this question
4

3 Answers 3

Reset to default
14

I don't think its bad, but external links have a bad habit of going away over the life cycle of a solution. When doing so, I recommend putting a sufficient summary that will help the reader if the link is not longer functional.

Improve this answer
1
  • 3
    Adding a summary useful for two reasons: 1) As Jim pointed out, it helps the reader understand whether or not the link is outdated, and 2) it forces the developer copying the code from the link to understand what they are copying. This helps to make sure that code isn't only being used because "it fixes the problem".
    – Mage Xy
    Commented Apr 7, 2016 at 15:37
7

This is why companies should have its own knowledge repository. For instance, my company have a corporative Redmine which is used for project's management, ticketing (bugs and tasks tracking) and the tool I use most, a wiki. All these features per project :-)

What do we have at project's wiki?

  • Links to documentation: Functional, Technical, Architecture, requirements.
  • Actors involved: Project Manager, Devs, Customer's Key Account managers, ...
  • Description per environment: Virtual Machines, O.S, servers, configurations...
  • Misc: Any important/interesting thing (related to the project) learnt during the project's lifetime.
  • Some more pages.

I put bibliography (links) at Misc wiki. But only from those I trust:

  • Stack Overflow: Positive votes and well argued
  • Software Engineering Stackexchange: Positive votes and well argued
  • MKyong.com: I like this page. It's really useful and its tutorials are really easy to follow
  • MDN
  • W3C.org
  • W3Schools: Its documentation is interactive (most of the cases) and user-friendly.
  • OWASP: For referencing issues related to security and vulnerabilities
  • Official web pages: Sometimes the best tutorials or explanations are at official web pages.

My bibliography comes with a summary typed down by me, in order to ensure that I have understood what I'm linking to. I try to keep Javadoc as clear as possible. Every link in the code is referencing the Redmine's wiki or the Redmine's issue code.

In absence of tools like Redmine, I found to be useful Markdown files to be useful for these purposes. Overall for developers due to these files are in the SCM and comes along with the code.

Improve this answer
2
  • 1
    I agree with everything except trusting W3Schools.com. You can find most of what's there on MDN which has way more authority.
    – Alternatex
    Commented May 23, 2016 at 8:45
  • 1
    W3schools has been around longer than MDN. I may be wrong, but I think W3schools has more content, tutorials and web technologies documentation. Despite its issues it keeps been one of the best reference for beginners because its content is way more user-friendly and interactive. On the plus side MDN has a great community supporting its content. But on the down side, it could never be impartial in its documentation because it has a browser to defend. Anyways, I'm in agreement with you, now a days MDN seems to have more authority. if you don't mind, I will add the reference to my answer.
    – Laiv
    Commented May 23, 2016 at 10:45
4

Links to the web are somewhat problematic as documentation because the internet doesn't guarantee that the content you're seeing behind them will be the same that a future doc reader will see. If possible, strive to link only to resources that are very unlikely to change.

For instance, when you link to Wikipedia, you should link explicitly to today's version rather than the generic article name. For stackexchange.com, well, at the moment it looks unlikely to go away, but questions get edited or even deleted all the time, and in five year's time a hot new gathering point might have come along. I wouldn't risk hanging documentation that carries substantial business value on a site that is so external to your organization.

Improve this answer
1
  • "Wayback Machine - Internet Archive" (web.archive.org/) is a good place to check for deleted content.
    – Kromster
    Commented Sep 13, 2016 at 9:23

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

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