October 21, 2007

C# Multi-line XML Documentation Comments

I was just checking out the documentation on MSDN about XML comments and I discovered that C# supports multi-line comments for XML documentation as well:

 * <summary>Hello World!</summary>
public void HelloWorld() { }

Interesting, but I wouldn't recommend using multi-line comments for a few reasons:

  • They do not support Smart Comment Editing, where by Visual Studio inserts multiple comment lines and an empty summary tag automatically after starting the comment, which in this case is done by typing /** instead of ///.
  • Intellisense is limited:
    • top-level tags are listed but context is ignored (e.g., the para tag is never listed, even if the cursor is within a summary element).
    • Entering a tag name and pressing enter will not produce a closing tag automatically.
  • The rules for processing markup may be problematic since the compiler will look for a prefix pattern consisting of white-space, an asterisk and more white-space; however, a slight change in formatting in the prefix of one or more lines (e.g., less leading white-space) may cause the compiler to include one or more asterisks as part of the comments.
  • They are certainly not as common as triple-slash comments and will probably be confusing to most people (I know if I were to have seen this format used, and I already may have, I would have doubted whether it was even valid.)

I'm curious to know if anyone has found this feature to be more useful than triple-slash comments, and why :)

December 01, 2006

References, Citations, Paraphrasing and Plagiarism

There is a fair amount of research and work that can go into obtaining information when a poster responds to a newsgroup question.  Information is commonly obtained through someone else's testing or research and is simply paraphrased or even quoted.  I believe that's understood by the general population of newsgroup readers.  So at what point does a poster's information become plagiaristic, if ever, when their sources aren't referenced in a newsgroup post? 

It's no secret that a large majority of information found in newsgroups is based on the poster's memory of the subject matter.  However, much of it can be attributed to actual fact-based sources such as books, articles and other newsgroup posts.  Anything stated in a newsgroup post can easily be interpreted as fact even if it's not.  Information posted without fundamental tests being performed by the respondent themselves are sometimes qualified with, "AFAIK" (as far as I know) and "IIRC" (if I remember correctly).

If it's just common knowledge that, as for unreferenced information found on newsgroups, the testing required to have derived it is not of the respondent's effort but instead the effort of unreferenced sources, then what if the information derives purely from the respondent's own testing and experience?  Posters would only get credit for having derived their own knowledge if they explicitly state that the information provided by them was acquired solely through personal testing.

Maybe posting based on personal testing is uncommon enough that it's fair to just assume that posters have retrieved their information from other sources or just have so much experience with the subject matter that testing isn't required.  Since much or all of the information of the subject matter is coming off the top of their head, to enable quick responses, it might not be fair for OPs to expect references without explicitly asking for them.  In that respect, newsgroups are treated more like personal conversations.


So this brings me to the point of syndication of USENET content and how what was once simple, off the top of your head opinion being expressed in a conversation between one or more thread correspondents, may become reference material much like books and articles to the possibly millions of users that search groups.google.com every day [1].

In school we learn about plagiarism and how bad it is, but we do it all the time in computer science.  In a way, there's just so much information out there that it's used on-demand, like children with our hands in a jar full of jelly beans. It might not make sense to reference the sources of all information provided in a newsgroup, web article, or even books.  Paraphrasing, to that point, is commonplace in newsgroups because it's just too difficult to locate all sources of information when speedy responses are preferred and expected (although not all OPs expect speedy responses.  Especially the ones that are familiar with newsgroups).

Usefulness in references

For one thing, quotations and fact-based opinions found in posts are usually not the entire story anyway.  References provide to readers a more complete description and reasoning, in its original context.  Without these references, the information being provided out-of-context may be easily misinterpreted, and then even worse, assumed to be accurate and complete.  People who prefer newsgroup posts to be short can't have it both ways.  Either you need to provide a reference to the complete information, or provide the complete information within the newsgroup post itself.  This reduces ambiguity in replies, providing more accurate information to readers.  I prefer a reference link over a long post where the source itself is easy to understand or interpret.  If that's not the case, I believe a fuller description in the post may be in order.  There's also the idea that any missing references or incomplete information will be supplemented by another respondent, but I doubt that possibly ignorant expectation disqualifies plagiarism.  I'm sure in many cases that OPs have read the references already but simply wanted clarification.  I'm not sure how or if that situation particularly applies to this topic, however.

References also enable readers to perform further research on their own, given a good place to start.  Without references, readers are forced to perform their own searches but in many cases they don't possess the necessary skills to perform Internet research without a helping hand, which is why they may have come to newsgroups in the first place.

In consideration of time and memory

To relax my arguments a bit, I must say that I don't expect everyone to always reference their sources in newsgroups.  If you're not performing research but instead answering from memory, then I think it's reasonable if you don't always reference your sources, but it's certainly desirable for the reasons I've listed above.  If you invest the time to find a good source that agrees with the information you are providing, I'm sure it will be much appreciated by readers.

Format and placement

Outdated links floating around in USENET posts are just clutter, however a reference list appearing at the bottom may prove to reduce some of the clutter found in newsgroup posts instead of in-line referencing.  Long after reference hyperlinks become invalid, the information found in a post may still prove to be useful, but having an invalid link right between two informative paragraphs or sentences reduces the readability of the post in which it's referenced and serves no useful purpose since the link no longer works.


Are newsgroup posts supposed to be small enough where citations and references (as opposed to in-line referencing, on occasion) aren't expected or doesn't need to be standardized?

I wonder if it's a lack of standardization or precedence that most respondents feel like it's unnecessary (or just don't bother) to reference and cite the sources of their information, where applicable.  So here's my proposal for a simplified, standardized idiom for citing and referencing within newsgroup posts.

If anyone is aware that these standards or anything similar exists already, I'd love to see some links to your sources submitted as comments, please.

Newsgroup citation and referencing standardization based on [2,3]:


  • Maximum length of lines in characters (based on common newsreader capabilities)
  • International character sets (e.g., reference to a book title published only in French)
  • Should we reference the author? publisher? dates?
  • How do we reference sections in web articles?  pages in books?


  1. Citations in posts should use the same standards as specified by [2].  For example, the [2] that I've just used to cite [2] :)
  2. Respondents should post a list of references after their entire signature.  Here is an example reference list, appearing after my signature, that could be included in newsgroup posts that cite these resources (also serves as the reference list for this blog entry):

Dave Sexton

[1] Search Engine Watch, Searches Per Day

[2] IEEE style documentation

[3] IEEE style edition § Web Page

[4] IEEE style edition § Individual Author

And here's an example book reference based on [4]:

[5] J. Writer, Computer Science, Reading-Material Press, 1996.
pp. 78-96: Artificial Intelligence

As always, I'd love to hear from anyone that has something to say about this post.  Drop me a comment.