7

Possible Duplicate:
Is it OK to put a link to Q&A sites in a program's comments?

I'm creating a powershell / C# host and want to add the following comment

// This method cannot be called multiple times on a given pipeline. The state of the 
// pipeline must be NotStarted when Invoke is called. When this method is called, it
// changes the state of the pipeline to Running. 
// see http://msdn.microsoft.com/en-us/library/windows/desktop/ms569128(v=vs.85).aspx
if (pipeline.PipelineStateInfo.State == PipelineState.NotStarted)
{
    Collection<PSObject> results = pipeline.Invoke();
}

Is this an appropriate comment? What would you improve about it?

Community
  • 1
makerofthings7
  • 6,068
  • 2
    Add the link and a quote from the article. In case Microsoft moves or rearranges the original document you still have some reference. – Makach Feb 11 '12 at 18:27
  • @pdr Not an exact duplicate in my mind, as one needs to differentiate between links to documentation like MSDN and links to sites like Stack Overflow. See my answer below. – PersonalNexus Feb 12 '12 at 09:30
  • 1
    Is there someway you can structure the code to ensure this is only called once? I ask because comments usually are a sign that the cod e needs explaining, which is bad because the comments could become out of sync with the code that it's commenting. – George Stocker Feb 13 '12 at 00:40

6 Answers6

12

An external link is fine, perhaps with a brief synopsis on why said link is interesting. If at all possible, keep the whole comment on a single line.

If you are concerned that the link will be invalid in the future then make a local copy of the web page (Internet Explorer allows saving a whole webpage including images in a single file) and put the file in your documentation folder and link to that.

  • 7
    Did you just recommend using Internet Explorer? – mowwwalker Feb 11 '12 at 20:17
  • @user828584 For this purpose, yes. –  Feb 12 '12 at 11:20
  • 2
    Chrome, Firefox, and Opera (and I would suspect Safari as well) offer this feature. One does not have to use IE. –  Feb 12 '12 at 13:00
  • 4
    @GlennNelson Chrome, Firefox and Safari do not offer to save in a single file (the MHT variant). I've found that IE functions better than Opera in this regard. –  Feb 12 '12 at 13:06
7

The point of a comment is to explain why something is coded the way it is. Your comment is a good explanation why you have that extra check of the pipeline state there.

I think link is redundant though, because it is merely pointing to the current version of the documentation for the Invoke method. Unless your editor has support for clicking on such http-links, I would think it's faster to just press F1 on the Invoke method to bring up its documentation. Links might also change and using the help system to get documentation for a method seems the more natural way to get the most up-to-date information on a method.

Things would be different, however, if that was a link to a Stack Overflow question or some other source that solves a particular issue you had with a piece of code, e.g. information beyond what is provided in the official documentation. Especially if it took you a while to find online, it might be worth keeping the link to it in your code. But since even Stack Overflow posts aren't guaranteed to be around forever, making a local copy of the post might be more sensible if the information is critical to understanding a piece of code.

PersonalNexus
  • 3,019
5

It's always nice to find a short comment where it is necessary. I support my teammates when they place a hyperlink to a good knowledge source instead of writing a long story about what's going on here. This approach cleans your code and keeps your comment up-to-date.

Igor Soloydenko
  • 422
  • 6
  • 15
1

Your comment is not needed as the code is clear enough to explain that it won't do anything if the state isn't NotStarted. If it is called multiple times then it has no effect. Maybe, you should consider the method name to clearly describe your method's intent.

On the separate case of putting references in your code, then yes add them in if they truly add value.

PenFold
  • 224
1

Yes.

Adding links to your code is a great practice, and what makes it better is that you're explaining your reasoning of doing so.

One thing I would improve about the comment though is to leave some space between the link and the comment for better readability.

Another practice (alternative) would be to, on top of of adding the link, make your comment an excerpt of the article.

Dynamic
  • 5,746
1

If you program is nontrivial, then your code must stand alone and pass the tests of time. Becuase if the source code is lost, then it will not be changed and read , but otherwise code can live on for a very long time. Some of the older SO users will have stories about code that is multiple decades old still running.

I've worked on systems that were still in active development after decades. Links to websites would be well broken by the time a new programmer wanted to read them.

As Neither MSDN or SO are guaranteed to be around, all a link does is irritate.

Sir Tim Berners Lee wrote a very impassioned plea for URL's to be constant, so that links would have value going forward. So far, not so successful. Maybe we'd have been better off if he'd patented the web and forced us to do it his way as part of the license terms?

Tim Williscroft
  • 3,553
  • 1
  • 22
  • 26