0

Often when coding I'll get stuck on a particularly tricky problem and will go about searching for a solution. More often than not this leads me to a StackOverflow question that provides a full or partial solution, often with code than can be used directly by pasting into the original code.

In some cases this can lead to code that looks unintuitive or does some seemingly unusual things - such as overloading existing methods in classes, reimplementing in-built functions with the same name or otherwise breaking some aspect of "good practise" to achieve a solution. Sometimes these look like bad practise, but due to problems in the code

In cases like these I often find myself including a link to the answer that I've implemented, with some brief explanation rather than rewriting or duplicating verbose explanations.

Is including URLs to solutions for these kinds of problems in comments a common practise, or is there a better way to document this kind of code?

As an example of this kind of issue, I recently asked a question about resolving a conflict with the Python property decorator, where the solution was to rename the Python in-built function and included a link to the question in the code.

Community
  • 1
  • Isn't this more appropriate for meta.SO? Also if you have a better solution why not posting as an answer and downvote the inferior other solutions? – NoDataDumpNoContribution Jul 24 '14 at 08:35
  • 1
    @Trilarion this is a question of the practices of documenting code in one's own comments. It is kin to questions like [Do TODO comments make sense?](http://programmers.stackexchange.com/q/125320/40980) and many others in the tag [tag:comments]. The question is not about SE, or the SE software. It would be completely inappropriate on meta - see [whats meta](http://stackoverflow.com/help/whats-meta) and the bit "Meta Stack Overflow is the part of the site where users discuss the workings and policies of Stack Overflow rather than discussing programming itself." –  Jul 25 '14 at 13:44

2 Answers2

4

As links can get broken or otherwise invalidated, you should not depend on them for your documentation.

If you write something non-obvious based on an answer on StackOverflow or based on some other content on the internet, then you should include enough information in your documentation about what the code does and why it is written that way that future maintainers do not need to follow the links, but can understand the code from the documentation alone.
You can always include the link as a place where more information can be obtained. It can also be useful if you want to check later if the advise that was given at the time is still considered the best advise today.

Bart van Ingen Schenau
  • 71,712
  • 20
  • 110
  • 179
2

I do this a lot. I will write comments linking to SO answers, linking to Github issues, linking to anything where more information about the specific problem/answer may be found.

There are caveats to doing so:

  • In the case of SO questions, the question might be deleted, or the answer might edited or deleted, and it may no longer be relevant;
  • Any other links may also have their content edited, or be removed altogether.
sevenseacat
  • 3,084
  • 1
  • 23
  • 23