Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

I found out nowadays, instead of writing comment for source code which requires clarification, most of the time there is just a link to stackoverflow Q&A. Does your source code also having such characteristic?

share|improve this question
7  
I'd argue against it for the same reason that stackoverflow in general itself argues against just putting up links to sources - to protect against link rot (of various types). –  Clockwork-Muse Jun 4 '13 at 16:41
1  
A question asked on StackOverflow when the code was written will not answer all the questions someone could have when they read your code. The question probably wasn't even written with the intent to show someone how to understand it. –  Korey Hinton Jun 4 '13 at 17:04
7  
This is horrid in so many ways. –  Robert Harvey Jun 4 '13 at 17:35
add comment

closed as not a real question by Joel Etherton, Robert Harvey, gnat, psr, Karl Bielefeldt Jun 4 '13 at 18:22

It's difficult to tell what is being asked here. This question is ambiguous, vague, incomplete, overly broad, or rhetorical and cannot be reasonably answered in its current form. For help clarifying this question so that it can be reopened, visit the help center.If this question can be reworded to fit the rules in the help center, please edit the question.

5 Answers

Links should not replace good comments. Simply putting a link does not always display the intended logic. When going back to review old code or someone else's code, it is much more helpful have notes about what he or she was trying to do.

Aside from that you also run the risk of that link not working in the future due to moved/missing web pages, etc.

I think it is acceptable to have links in addition to comments when the link can provide more detailed information, such as details or use of a specific library.

share|improve this answer
4  
+ Any reference, in any medium, without annotation which includes a rationale (why that reference) and context (specific where in the reference), is of little value. Without adequate annotation naked references just make the 'documented' concern more confusing. –  JustinC Jun 4 '13 at 17:05
1  
I frequently leave links in my comments, but usually as a reference after explaining why/how I did something. As mentioned above, a link is not a replacement for a good comment, but I find it can be a pretty good piece of additional info. –  Josh Buhler Jun 4 '13 at 17:24
add comment

A link is good as "see more here", but should not replace concise summary

EDIT: if it was unclear: I definitely require the comment text to have major points right there. But adding a link to more elaborate explanation is welcome. And especially pasting in a pageful of text would not be welcome if it can be easily and reliably accessed by other means.

While I'm at it: at places I worked we always had Wiki, and project-related things were there including design documents. IMO linking to those pages is a good idea, and there it's ok to even reproduce text from external source and leave a link to the original.

share|improve this answer
add comment

Links don't replace comments, and they shouldn't. Replacing a comment with a link is taking the risk that your link could be broken in a near future.

Imagine that someone is maintaining your code and see the link, but the link is broken and no one knows what the content of the link said before. It's basically the same that don't have made any comment (or made it and erase it after).

Use links only as "See More" cases, as @BalogPal said. And I recommend that only if you is the one that's keeping this link online.

share|improve this answer
2  
I would argue that even if you are the one keeping the link online, there is no purpose to replacing a comment with a reference to documentation that is found elsewhere. –  Korey Hinton Jun 4 '13 at 17:20
1  
@KoreyHinton I agree with you. I edited the answer. :) –  Diogo Moreira Jun 4 '13 at 17:27
    
+1 Good point about broken links. Thanks for the edit. –  Korey Hinton Jun 4 '13 at 18:03
add comment

I would consider that lazy, and not in a good way. In the same way that link-only answers are not welcome here on Programmers, a link-only commit message may lose all usefulness if the link becomes invalid.

In my view, a commit should always have human-readable content summarizing the changes included.

share|improve this answer
add comment

There are to other factors which are important but weren't mentioned in other answers:

  1. Messages in logs are searchable. If you put links instead of messages, there would be no way to find the specific revision through search.

  2. It is not unusual to look at the log for a specific pattern. For example, if all revisions which were limited to refactoring start with "Done [minor] refactoring of ...", if all revisions which solve bugs have messages in a format "Solved the issue ..." and if all revisions which add a unit test reproducing a bug are described as "Added unit test reproducing the issue ...", then it makes the log faster to read. A message like:

    Solved the issue with parametrized queries causing an exception by migrating the code to pyodbc.

    can be easily found: you know that the revision solves a specific issue, and you even get additional info about the issue itself and the solution. Instead:

    http://stackoverflow.com/q/16636118/240613

    requires you to copy the link, open a new tab in the browser, paste the link in the browser, press Enter and read lots of stuff just to discover that it doesn't explain what was the revision about: was it solving an issue? Was it solving it by using pyodbc, or by avoiding parametrized queries?

share|improve this answer
add comment

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