Talk:Comment (computing)

From Wikipedia, the free encyclopedia

 This article is within the scope of Computing WikiProject, an attempt to build a comprehensive and detailed guide to computers and computing. If you would like to participate, you can edit the article attached to this page, or visit the project page, where you can join the project and/or contribute to the discussion.
Start This article has been rated as Start-Class on the quality scale
Low This article has been rated as Low-importance on the importance scale

Contents

[edit] Spammers

Why do spammers continually want to change this page? -- Mattworld 00:53, Nov 16, 2004 (UTC)

I don't know what their problem is... both the talk page and the article are targets for some reason. Moreso than any other articles I have on my watchlist. -[Unknown] 08:27, Nov 16, 2004 (UTC)
Most wiki spamming tools assume /wiki/Comment will be some sort of guest book or comment page. --Sam Hocevar 23:56, 24 Nov 2004 (UTC)

[edit] NPOV

I added an NPOV-dispute marker to the page because of the authoritatively-stated opinions on how they are to be used. I actually agree with most of those opinions, but I don't think it's appropriate for Wikipedia to give them as its own. Rather, Wikipedia should give information about various opinions on the good use of comments - GNU's coding standards, Linus Torvald's coding instructions, etc. - without taking a side. (I'm kind of amused - I never thought I'd be adding an NPOV-dispute marker to a page on programming-language comments, of all things.) Ruakh 03:59, 8 Mar 2005 (UTC)

Addendum: all of the current non-NPOV text was added at once, in the revision of 24 January 2005. Ruakh 00:02, 14 Mar 2005 (UTC)

This article has gone through a minor re-write. Maybe we could look again at the NPOV problem and decide whether it still exists and if so, what to do about it. Shinobu 00:41, 6 Apr 2005 (UTC)

I do still think there's a slight NPOV problem, but your rewrite helped it to the point that I think it's okay to remove the NPOV marker now. I'll do so. Thanks for your changes! Ruakh 17:13, 6 Apr 2005 (UTC)

If I could do anything to make this article any more neutral, I would be most glad to help. Shinobu 20:08, 6 Apr 2005 (UTC)

[edit] XML comment syntax

I think there is way too much examples for XML and consorts. The various examples with added minusses are about as relevant as added C examples containing various numbers of stars would be. Also they clutter up the list.

Moreover, due to the structure of the rest of the list it might seem to an unsuspecting viewer that the examples actually denote different syntax, instead of variations on one syntax. I'll be removing the spurious examples. Shinobu 22:58, 5 Apr 2005 (UTC)

I disagree with this statement: "The various examples with added minusses are about as relevant as added C examples containing various numbers of stars would be." Note that in SGML, <!-- comment -- code -- comment --> contains both comments and code. (See the HTML 4.01 Strict Document Type Definition for examples of this.) Therefore, while perhaps not so many examples are needed, I think you're out of line to remove all the examples and explanation.
Also note that while XML is a subset of SGML, it does not fully support SGML comments: all valid XML comments are valid SGML comments, but the reverse is not true.
I've therefore reverted the parts of your change that relate to XML vs. SGML. Ruakh 17:10, 6 Apr 2005 (UTC)

Thanks! I should have read the docs more thoroughly. The part about the --'s I just did not notice. I have updated the layout for better readability. I hope the *:-trick works for everyone. You're always welcome to drop me line! Shinobu 20:11, 6 Apr 2005 (UTC)

[edit] List sorting

It seemed evident to me that originally the lists were supposed to be sorted on alphabet. I have re-sorted the lists, but a question has popped up in the process. What is our stance on those items that are examples for more than one language? Shinobu 15:20, 10 Apr 2005 (UTC)

I don't know if we really need a stance. I don't think the current or no order appears to be confusing to readers. -- Taku 00:46, Apr 11, 2005 (UTC)
I'd say, go in alphabetical order by the first language listed in the example's label. Now the question becomes, which language should get listed first in an example's label? I'd say that the most important language should be listed first (which is inherently NPOV, I suppose, but I think there'd only be disagreement in very rare cases), unless the phrasing requires something different. For example, HTML is more important than SGML, but since HTML is an application of SGML, the "SGML, including HTML" phrasing makes more sense. Ruakh 15:45, 11 Apr 2005 (UTC)

In that case we can probably leave it as it is now. Shinobu 16:01, 11 Apr 2005 (UTC)

[edit] Example in usage

As for the example I added in the usage section, I thought that if someone see

list = [b, b, c, d, a];

he may think that a, b, c and d are not variables. So I changed it to

list = [f (b), f (b), f (c), f (d), f (a)];

Here, I think f looks like a function. If any of you can come up with the better one, that would be appreciated. -- Taku 00:46, Apr 11, 2005 (UTC) I think most people would think they are variables. (Most languages quote strings.) However, it does not matter for this example wether a ... d are variables or not. If taken as strings, the reader just sees the special case a = "a" etc. Since you used arbitrary variables this does not matter. The example would have served equally well if the list would have been [a, a, d, a, b] or something entirely different. So reading the variables as strings is just taking an arbitrary example, which is what you intended in any case. Introducing an extra function is not necessary.

So what to do? 1) Leave it as it is. 2) Revert it. 3) Use strings. 4) Leave out the "list="-line. (And maybe rename list to something fancyful.) 5) Retrieve the list via a function call. list = files_in(my_folder);

I hope this helps. I'm personally in favour of 4 or 5, but I encourage you to use your own imagination, since there must exist examples I overlooked. Cordially yours, Shinobu 01:26, 11 Apr 2005 (UTC)

[edit] Whitespace?

The remark about comments being regarded as whitespace is not necessarily true. In HTML for instance, HT<!-- comment -->ML results in "HTML", not in "HT ML". Also I seem to remember some old C compilers allowed one to glue identifiers together using /**/, which was useful because ## was not supported back then. Shinobu 02:06, 12 Apr 2005 (UTC)

Yeah, I think that's simply an error. There are plenty of languages where comments are less significant than arbitrary whitespace. I'm reverting that change. Ruakh 05:30, 12 Apr 2005 (UTC)

[edit] Usage

  • Automatic documentation generation
  • Other uses

Shouldn't these be in the Usage section? The flow of the article feels a bit illogical as it is now. Shinobu 05:09, 18 May 2005 (UTC)

[edit] Does the "summary" section have to be so long?

I really don't think it's necessary to mention every technique that any language has ever used to indicate comments. I think it would suffice to state that nearly every human-writable computer language has had some mechanism for including comments, and then give a few characteristic examples of some different types (say /* */ and //, as they're popular multiline and one-line methods that a lot of programming languages use, plus <!-- --> because it's of special interest to Wikipedians, and possibly BF-style because it's quirky and can convey the point that not all languages necessarily use even the same sort of approach to indicating comments).

I'm bringing this here, rather than just editing the article myself, because so many people have added to the list that, according to the generalized pigeonhole principle, at least one of the following is true:

  1. a lot of people think it is useful.
  2. a lot of people have contributed without considering whether it is useful.
  3. a lot of people have contributed even though they think it's not useful.

And in case #1 of these is true, I want to hear why. :-)

Ruakh 00:48, 29 December 2005 (UTC)

As a programmer I just enjoyed looking through the different approaches to comments there are. Maybe one day, knowing that all comment syntax is documented here, I might be able to come here for a quick referece if I am using a language I never used before. For example: I have to maintain some old code written in an obscure dialect of BASIC and nobody ever commented anything. Anyway, does it matter whether the page has too much information. Readers can use the TOC link box at the top of the page to skip over all the examples.JesseHogan 02:39, 29 December 2005 (UTC)
Firstly, if you want information on how to create a comment in a specific language, then wouldn't it make more sense to look at the article on that language, rather than at the article on comments in general?
Secondly, I'm a bit concerned by your choice of example: "an obscure dialect of BASIC" (emphasis mine). Does this mean that every language that's ever existed should receive a note on how it denotes comments?
Finally, I think your first sentence - "I just enjoyed looking through the different approaches to comments there are" - is actually an argument in favor of trimming. Currently, with each different symbol receiving its own list item (some symbols receiving multiple list items - /* */ is listed five times, for example), it's more difficult to get an overall view of the different approaches. There aren't that many different approaches, and if you want to find the less-common ones, you have to slog through a long list of almost-identical ones.
Ruakh 03:02, 29 December 2005 (UTC)
You make good points but I think our disagreement is that it doesn't bother me that the article is big but it does bother you. I'm not going to be upset if you delete all the examples so go ahead and delete them of its that important to you. JesseHogan 07:16, 31 December 2005 (UTC)
I kind of like the list... it gives you a kind of comparison that the individual pages on the languages themselves can't give. If it really bothers you to have it here, maybe you could move it to a new page instead of deleting it outright? Shinobu 01:27, 3 January 2006 (UTC)
I find the list useful as a reference, because it denotes the exact syntax of comments for several languages; it's also interesting. Wikipedia is not paper, and I see no need to shorten it or move it to another page, though the latter is certainly the better option. I'll also, because I believe in full disclosure, point out that I started the list in August 2003, and have enjoyed seeing people contribute to it and greatly improve it. See [1]. -- Mattworld 02:53, 3 January 2006 (UTC)

[edit] if (FALSE) { ... }

I deleted this from the R entry. While if can be used in this way to prevent a block of code from executing, and R's syntax makes it easy to exploit for commenting purposes, this is really a feature of block-structured languages as opposed to a "comment" tool. You might as well say that the C preprocessor trick #if 0 ... #endif is also a way to do comments. -- 168.140.181.4 00:22, 9 October 2006 (UTC)

I don't see why we shouldn't include both as ways to include comments. StuRat 04:41, 18 October 2006 (UTC)
Well, you shouldn't include the C trick because it's not a way to do comments. The tokens inside the #if 0 still have to lex properly, or the compiler will get upset. Languages typically have very few and unobtrusive restrictions on what can go in comment text. Having to look like C tokens is not a small restriction, in my book. Besides, C already provides a (couple of) perfectly good comment syntax of its own. --Quuxplusone 00:23, 30 November 2006 (UTC)
I think I should point out that a lot of compilers (most?) don't care what appears inside blocks of text discarded by the preprocessor. Usually you can even run the preprocessor on non-C files if you wish to do so. Shinobu 05:45, 7 December 2006 (UTC)

[edit] docstring

Visual basic supports 'docstrings'? Can you provide a reference for that? It seems a tad questionable, because all languages support documentation inside comments, but not all languages support it natively, and not all languages support direct manipulation of docstrings in the same manner as variables, objects constants. If Visual Basic does indeed have support in this more specific sense please provide a ref here. Thanks! dr.ef.tymac 16:57, 16 November 2006 (UTC)

You can assing comments to class members and the like via the object browser. They are saved with your source code. If you later browse to the item in the object browser, regardless of whether you use the source or compiled version, you see the same comment. This is because they are saved in the executable / dll as well. Apart from a regular docstring a link to a helpfile is also supported. To access these comments from within a VB app, you need to use the OLE / COM API, but it can be done. So they fall well within the boundaries of our docstring definition.
Quotation:
Options
Displays the Member Options dialog box, which you can use to add Help information or comments about modules, procedures, classes, properties, and methods that you define in your project. This lets you scroll through a list to see descriptions and comments for the procedures in your forms and modules.
"Object Browser", Visual Basic 4.0 help file. Shinobu 08:31, 17 November 2006 (UTC)
Ahhh, now I see what you are talking about. It is probably not directly intuitive to someone unfamiliar with the VB coding practices and IDE, but it arguably does meet the definition as you said (although rather circuitously). On that basis, I agree VB at least deserves a mention. You might, however, consider adding a mention of VB to the docstring article, as the content was moved yesterday. dr.ef.tymac 15:01, 17 November 2006 (UTC)


Can someone give a citation? VB does, seem to have the capability, but are their VB programmes out their that use the information in their comments to modify their behaviour? --Paddy 06:34, 18 November 2006 (UTC)
I think it's primarily used by libraries, so that their documentation will show up in the object browser and similar tools (like the one distributed by ActiveState Perl). For instance, if you design a custom control, you can document properties and methods. They are essentially IDL docstrings (which are extensively used by the VB runtime library). The way it ends up in the source code looks like this:
Public Sub MyMember()
Attribute MyMember.VB_Description = "MyMember performs a very useful action."
...
End Sub
(Although the IDE hides it from normal view, opting to make them editable through a dialog box instead, as described above.) So I guess you could do a web search for VB_Description. Shinobu 14:37, 27 November 2006 (UTC)
And look what I found: vbACOMTLB.tlb. At first glance, you can look at docstrings, help ids, names and type information. Shinobu 15:17, 27 November 2006 (UTC)

[edit] Java docstring

I didn't think Java supported docstrings, i.e. comments linked to certain objects such as class and method definitions that are accessible at runtime?--Paddy 19:22, 16 November 2006 (UTC)

Not unless this is some sort of oblique reference to Reflection (computer science). Maybe the writer was confusing this with doc comments?
 /**
  *  @author Ed Poor
  *  @version 3.5
  *  @return square root of the supplied argument
  */
There's a bit about Java reflection here. --Uncle Ed 19:33, 16 November 2006 (UTC)
Need verification, if Java has support for 'docstrings' as defined in the article (i.e., more than just Javadoc, and more than just reflection [unless Java has a reflection facility that works on comments as well as code] ... please provide a ref. Otherwise Java should probably not be on the list).dr.ef.tymac 19:41, 16 November 2006 (UTC)

[edit] Article structure, disambiguation and scope

This article recently underwent some non-trivial changes without discussion on this talk page. This is a request to all interested parties for discussion first. Thanks! dr.ef.tymac 02:44, 26 December 2006 (UTC)

Thanks dr.ef.tymac. I'm happy that we can have a discussion and hopefully reach a consensus. Likely I'll not reply right now because it is about 4am where I live, so I'll likely go to sleep in a few minutes. Of course I'll keep an eye on it tomorrow (i.e. today) :-) Right now I'm fixing a ton of bad links which should actually point to this article but do not; after that we can have a clearer view of our alternatives (one of the links, for instance, is from INI file and of course an INI file isn't written in a *programming language*) —Gennaro Prota•Talk 02:56, 26 December 2006 (UTC)
I'm exhausted now. Here's a selection of articles on which I have repaired links related to comments:
It might help reach a consensus. —Gennaro Prota•Talk 03:22, 26 December 2006 (UTC)

Comment types: A review of all the preceeding links by User:Gennaro Prota seems to indicate that all relevant denotations and connotations of "comment" refer to one (or more) of the following:

  • Feedback comment system
  • Comment (computer programming {subtype of computer language})
  • Comment (ini file {which is a sub-species of configuration file.})
  • Comment (css stylesheet {arguably a sub-species of configuration file and computer language} )
  • Comment (markup language {not in links, but mentioned previously} {subtype of computer language} )
  • (To be determined: are there any other meanings for a more "exhaustive list"?)
  • (?? Edit summaries? Comments in collaborative-editing?)
There are also the comments that can appear within "text" documents. For instance, Microsoft Word has a comment option that enables a comment to be attached to some text in a document. What about the comments that appear on physical labels (eg, white sticky labels and other non-electronic forms) or written on a DVD to note its contents? A "comment (computing)" article ought to cover all uses, in fact many of them are not specific to computing. Derek farn 12:55, 26 December 2006 (UTC)
Hmm, these all seem excessive to me except perhaps for Microsoft Word comments (we could add a link to Microsoft Word in the dab page; then of course there should be mention of them in the linked to article); but for the other uses... at most they could be cited as examples in a dictionary, IMHO. —Gennaro Prota•Talk 13:31, 26 December 2006 (UTC)
Article Scope-creep: The point just made User:Derek farn is one reason why the change to "computing" seemed a tad problematic (IMHO). Personally, I lean toward reforming this article to focus on "computer programming" and including content to indicate the other connotations, making liberal use of the dab page. Another problem is "comments" in microsoft word (and related software) has more than one meaning (e.g., "user annotations" {in collaborative editing}; "sticky-notes-style comments"; comments in "file metadata" and so on). Im willing to attempt reformed edits if Gennaro Prota can continue to identify clean-up issues. Thanks! dr.ef.tymac 17:35, 26 December 2006 (UTC)
I don't see it as article creep, I see two different articles one dealing with the general subject of all kinds of comments in computing and one dealing with comments in programming languages (ie, the current article). The general subject of comments has fuzzy boundaries; what is a comment and what is a description? I don't think it is a good idea to try and shoe-horn in Microsoft Word comments into a programming language article where they clearly don't belong. Derek farn 18:39, 26 December 2006 (UTC)
Sounds like we agree then. I mentioned "scope creep" simply to suggest avoidance of the "shoe-horn effect" that you refer to. It sounds like the only unresolved issue (so far) is the specific structure, titles and number of articles necessary to avoid the "shoe-horn". dr.ef.tymac 20:08, 26 December 2006 (UTC)

Proposal: Based on a review of the content, and other considerations:

  • i) Re-move Comment (computing) back to Comment (computer programming) {OR Comment (computer language), another option}
  • ii) Expand the the disambiguation page to reflect a more "exhaustive list"
  • iii) For the "short term" add "markup language" and "configuration file" style comments to the "other uses" section of Comments (computer programming {i.e., this article})
  • iv) For the "long term" expand "other uses" section into separate articles if and when content justifies doing so
  • v) For cases where the meaning is potentially "overlapping" or "unclear" point links to the disambiguation page, for other cases, point links to this article (or the "other uses" section herein)

Rationale: The rationale for this proposal is as follows:

  • The title "Comment (computing)" is vague; expert readers may be confused by it, and non-experts are likely to be misled;
  • The usage of (computer programming) has a high degree of semantic affinity with "configuration file", "markup language" and "css stylesheet", but a lower degree of affinity with "feedback system" and other types of comments used in "computing";
  • The retitle to "(computing)" may obscure the differing degrees of semantic affinity through over-generalization
  • There already exists an article (computer language) to deal with the difference between "INI file" and "programming language"
  • There already exists a disambiguation page, changes to which may require much less effort, and be much less jarring, confusing and potentially misleading than a re-title of this article and a wide-scale change of links.

Based on the timing of the Holiday season it may be likely that other interested parties may respond late to this ... something keep in mind before further moves, re-links and other labor-intensive actions. Important: Taking the effort to independently "fix a ton of bad links" may be worth some serious re-consideration in light of the above issues. dr.ef.tymac 05:57, 26 December 2006 (UTC)

Let me also point out the situation about "commenting out". We have:
There are possibly other similar entries. No doubt that a cleanup is in order. —Gennaro Prota•Talk 11:18, 26 December 2006 (UTC)
Commenting out: As User:Gennaro Prota indicates, the "commenting out" article also presents a case for cleanup. Is there a reason why "comment out" merits an independent article? If someone can make a case for why it does, fine. For now, however, I am going to put a merge reco on that article. Good job to Gennaro Prota for identifying these issues. dr.ef.tymac 17:00, 26 December 2006 (UTC)
Commenting out is an action performed by people and a recognizable construct in source code. It is a use of comments that is kind of different from "contains useful information". Doe sit warrant its own article? Depends how high you put the bar and I would not say that the Wikipedia bar is that high. Derek farn 18:39, 26 December 2006 (UTC)

[edit] Moving

Comments should be seen to once the merging is done.

This article was created ostensibly to distinguish different types of comments in "computing" from comments in "computer programming" (not necessarily the same thing). If the page is confusing to some readers, perhaps it can be changed into a redirect to comment. This article doesn't seem to be much more than a disambiguation page anyway. dr.ef.tymac 03:21, 2 January 2007 (UTC)