Talk:Comment (computer programming)

article move

This article was moved to comment (computing) and then moved back to comment (computer programming). The article then underwent some changes including:

• addition of citations and references
• addition of new sections and content
• restructuring and refactoring of some of the preexisting content

Some items still outstanding:

• Article seems to assume "developers" are only ones who read source code (may need to rethink in light of open source)
• The existing comment (computing) article now needs considerable attention as it is now just a "stub"
• The separate Comment out article may need to be merged into this one. dr.ef.tymac 05:11, 29 December 2006 (UTC)
• Comments now is confused and odd.

re-add 2x reverted intro

Can someone please explain what is incorrect about the intro section as of my last edit? It was done to improve the article clarity and accuracy, but reverted twice without any discussion, and without fixing the existing deficiencies that I and another editor addressed previously. It is good to see this article move forward with discussion and consensus, let's keep up the good work, Thanks! dr.ef.tymac 11:21, 29 December 2006 (UTC) Follow-up: Added cite and additional clarification. Still welcoming all feedback, Thanks! dr.ef.tymac 11:54, 29 December 2006 (UTC)

Can somebody please explain what is incorrect about the intro section that existed for quiet some time before it was changed to something rather nebulous and ambiguous? While the new authors intentions may be good, the existing article has been reverted twice without discussion. Derek farn 14:19, 29 December 2006 (UTC)

Nebulous and ambiguous: Can you give a specific example of what you mean by that? Without something specific to point to in the article, it is impossible to make a good faith effort to address any deficiencies. Thanks! dr.ef.tymac 15:57, 29 December 2006 (UTC)

Please deal with my first point. What was wrong with the original wording? Derek farn 16:55, 29 December 2006 (UTC)

Still waiting for your answers: Again, you still havent answered my original questions, which I posed to you first. Please keep this thread on this specific topic so we can focus on one thing at a time.

I will even demonstrate my goodwill to you by patiently waiting as you to go create the other discussion thread, and I will happily address that thread also. Please reciprocate this goodwill by answering questions in the order they are posed, or at least explaining why you wont/cant/shouldnt answer. (see also, "pre-existing content" and "request for discussion on older content"). Thanks for helping to keep this discussion (and related article) well-organized! dr.ef.tymac 17:28, 29 December 2006 (UTC)

Follow-up: Also, please note it is not clear what you mean by "original wording" ... so it will help if you refer to a specific revision in the article history in the other discussion thread. Then we won't be "talking past one another" when we work together to resolve whatever issue may still be concerning you. Thanks much! dr.ef.tymac 18:33, 29 December 2006 (UTC)

Follow-up: The immediately following text seems to completely ignore my request to start a new thread so we can discuss this matter separately. It also ignores my request for simple "yes" or "no" answers to questions I already asked, so I can understand where the editor is coming from. Because of this, I am moving the text to a new thread myself, and leaving a fragment here so as not to misrepresent anyone else's words. dr.ef.tymac 20:04, 29 December 2006 (UTC)

So in other words you don't want to talk about the introduction wording that existed a week ago ... {snip} ... (see "text from a week ago")

Pre-existing content: 1) Time-span of content on Wikipedia does not by itself imply accuracy or quality (see e.g., here for a well-known example) if that was the point being made, I will dismiss it as incorrect and irrelevant, if that was not the point, please clarify. dr.ef.tymac 15:57, 29 December 2006 (UTC)

Request for discussion on older content: At the time this article underwent non-trivial recent changes, to my recollection, User:Dreftymac was the only user who requested additional discussion on the relevant talk page (instead of more remote user pages) in order to keep the article moving forward and improving, and to give a fair opportunity of participation to all interested parties. If someone else wishes to start a discussion about why some older content should be preserved, I welcome it! Please, however, start another discussion thread, so each individual thread has a chance to stay focused and on-topic. Thanks! dr.ef.tymac 15:57, 29 December 2006 (UTC)

What exactly is a "standardized way"? Comments are specified as part of the language definition and most language definitions I am aware of include comments in their definition of source code. The author of the cited reference uses the term "program code". What exactly is that? Derek farn 14:19, 29 December 2006 (UTC)

Standardized way: Ok, now we are getting somewhere. You mention a *specific issue that I can directly address*. Consider the ECMAScript Language Specification. In that language specification, there is a section called "comments" (§ 7.4 p 12). Consider next the Java Language Specification, in that language specification there is a section called "comments" (§ 3.7). Consider next the Extensible Markup Language (XML) specification, in that specification there is a section called "comments" (§ 2.5). You might notice that there is a pattern here. In fact, this is a well-established convention (a 'de-facto' standard, if you will, for language specifications, language references, and even basic tutorials). This is what is meant. If you can articulate this fact more clearly, in a way that is accessible, concise, professional, and not confusing to a general audience, you are more than welcome to have a crack at it. dr.ef.tymac 15:57, 29 December 2006 (UTC)

Follow-up: Good faith effort to reduce potential ambiguity of "standardized way" ... changing it to "common convention". dr.ef.tymac 16:11, 29 December 2006 (UTC)

Dreftymac: What you are saying (be it "Standardized way" or "common convention" is that most (if not all) programming languages contain comments. Fair enough, why not just say something along the lines of "All known programming languages contain some mechanism to embed comments in source code"? Which ever way it is phrase it is hardly a straightforward way of providing an introduction to the term. Derek farn 16:55, 29 December 2006 (UTC)

To be more precise: "common convention" conveys: 1) the subject matter of this article relates to a common element of programming languages; 2) this element is commonly documented in language specifications; 3) specificiations commonly document it in (roughly) the same way using identical terminology; 4) the issue of an established practice. Specific proposed improvements are most definitely helpful. Remarks strictly "along the lines of" or "anti-what-is-there-now", not so much. I do, however, appreciate all coordinated effort to continue moving the article forward. dr.ef.tymac 18:27, 29 December 2006 (UTC)

Program code: Before answering your question, are you contesting the validity of the cite itself? If yes, I respectfully request that you indicate why it is deficient. If no, then we can establish that the cite itself is indeed legitimate, and proceed on from there. This will be extremely helpful, so as to keep the discussion focused and on-topic. Thanks! dr.ef.tymac 15:57, 29 December 2006 (UTC)

A quick "comment" about the recently reverted contents

Hi guys,

I have quite a lot to catch up on the discussion we began on this (BTW, did it end? I see that editing is in progress) but really the point that comments are not part of the source code is ridiculous (the assertion that comments "are ignored" is close to meaningless too if one has a minimal idea of how a parser works, but that's what one usually gets when trying to explain things in a (over-)"simplified" way). Don't be offended, but could I ask those who are not programmers to refrain from adding to this article? —Gennaro Prota^•Talk 11:22, 29 December 2006 (UTC)

Hi Gennaro Prota: 1) can you indicate where you mean (in the article) that indicates "comments are not part of the source code"? I can fix the relevant section, but I'm not sure which specific part you mean; 2) The phrasing "comments are ignored" is used quite commonly in programmer reference books (at least in English, see e.g.,) are you saying this phrasing is always bad? or just misused in the article? If it is the latter, can you point out where so we can fix it?; 3) I am not sure how a person's "job title" applies to contributions on Wikipedia, especially since all editors (regardless of background) must satisfy Wikipedia:Verifiability. Is there a specific element of the article you were addressing with the "non-programmer" remark? dr.ef.tymac 11:43, 29 December 2006 (UTC)

Hi, the part in the article stating/suggesting that comments are not part of the source code was the initial table. As for verifiability, it is a great policy to have but of course doesn't prevent incorrect information. Basically, you can find that sentence in programming tutorials and entry-level books etc. where one just tries to "get started" but it is technically incorrect. As to the rest please never mind, I'm a bit wiki-stressed. I'm going to un-watch this article page, and sorry for my tone. —Gennaro Prota^•Talk 18:38, 29 December 2006 (UTC)

Initial table and response: The initial table was clarified specifically to avoid the exact implication you mentioned, thanks for the feedback. As far as far as accuracy, I agree with you that it is of utmost importance. I am not quite sure what you found to be "inaccurate" (as opposed to imprecise or analytically non-rigorous, which are not the same thing), but I'm happy to drop the issue if you are. I am sorry you are feeling stressed out, and I hope you are able to get a good rest and come back. You pointed out some weak points in the article that I had considered a long time ago, but never addressed. The end result is the article is now a bit more developed, and hopefully incrementally moving closer to "good article" potential. For that I say "hats off" to you :) Thanks! dr.ef.tymac 19:05, 29 December 2006 (UTC)

Follow-up: BTW, no apologies necessary and no offense taken :) I am just happy I don't have to post my C.V. or my master's thesis just for the continued honor to pitch-in on an article about, *cough* freakin' comments. :-P dr.ef.tymac 19:26, 29 December 2006 (UTC)

Returning back to have a look (can't resist :-)). The article looks much better now. The first footnote though is even worse than the sentence which talked about "ignoring" (think for instance of a typedef int unused_name; in the middle of a C function body: it doesn't produce any executable code, so is the declaration a comment? There are *tons* of constructs in a programming language which don't directly yield executable code; did I hear "metaprogramming"? :-)). Off-hand —and trying to reach a compromise between technical correctness and clarity— I'd phrase the lead sentence as follows:

Comments are pieces of text interspersed in programs' source code for explanatory or documentation purposes. Comments must be marked in a way that allows the program translator (interpreter or compiler) to recognize them as such, so that no further syntactis and/or semantic analysis is performed on them. In simple terms, this is often expressed by saying that comments are "ignored" (after they have been recognized) by the translator.

It must be further refined, but I'd like first to agree on the basic formulation. Last time a discussion was started it looks like I was the only one who refrained from editing (weren't we supposed to wait the end of the holiday season?)
One thing we might want to discuss is: consider for instance /* this is a comment */. What we consider comment, "/* this is a comment */" or just "this is a comment"? It makes a difference for the wording used in the rest of the article. —Gennaro Prota^•Talk 12:41, 31 December 2006 (UTC)

Hi Gennaro Prota: I have made a stab at starting a general purpose Comment (computing) article. At the moment it is not very cohesive and in need of lots of work. Derek farn 14:19, 29 December 2006 (UTC)

text from a week ago

So in other words you don't want to talk about the introduction wording that existed a week ago (ie, "In computer programming, a comment is a programming language construct that provides a mechanism for embedding information in source code that is (generally) ignored by compilers and interpreters but may be of use to people reading the source, or other programming tools that process the source such as documentation generators or source code management systems." and its ilk). You would much rather talk about your wording. So lets not work on perfectly good wording, but start on some poorly written new wording. Perhaps in a month or two somebody else will come alone and we can start again on his/her new wording and lets not talk about the previous wording. I have better things to do than waste my time on helping to improve wording that is far inferior to what was already there. Derek farn 19:17, 29 December 2006 (UTC)

Follow-up: I am happy to talk about *anything* here, as long as it is relevant to the article, and appropriate for this page. You might even remember me as the person who kept asking for more discussion. Anyway, It seemed reasonable to: (1) keep separate topics in separate threads; and (2) to first answer open questions (as a basic courtesy) before moving on to new topics, which was all I was asking for. dr.ef.tymac 20:33, 29 December 2006 (UTC)

Edits by Sangwine: First off, the text in your parenthetical is *not* the text that prompted my modifications to the article intro to begin with. You appear to be citing an earlier revision that was changed by User:Sangwine and not by me. (then the article was suddenly re-moved and reverted to an older version, obliterating contributions by more than one editor, and then we ended up here...) dr.ef.tymac 22:04, 29 December 2006 (UTC)

Readability: The text in your parenthetical does seem a bit wordy, especially for one sentence. It has a Flesch-Kincaid Reading Ease score of -19 (the higher the score, the more readable the text; some websites shoot for a 60 - 80 range), and a Flesch-Kincaid Grade Level of 29. On that basis alone, I can see why someone might have thought it was a bit much. That's my take on it though, I don't speak for other editors. dr.ef.tymac 22:04, 29 December 2006 (UTC)

Ownership of wording: Please note also, there is no "my" or "your" wording. Contributions to Wikipedia are just that. A review of the article intro indicates it retains a lot of the basis of previous edits, just with smaller sentences... dr.ef.tymac 22:20, 29 December 2006 (UTC)

Is that it? Your reason is creating a not particularly good new introduction was a Flesch-Kincaid Reading Ease score? Can I ask what scores you have found for other Wikipedia articles? Derek farn 01:33, 30 December 2006 (UTC)

I cannot make this any plainer to you: I did not originally change "your" intro sentence, User:Sangwine did, likely because it was very difficult to read. I don't know for sure because I am not him/her. The score is simply and neutral verifiable measure (for folks who don't like "nebulous and ambiguous" critiques, and who don't mind "wasting time" on improving readibility). As far as my own perspective, there are other issues besides that, but discussing them seems pointless without a two-way dialogue. dr.ef.tymac 03:18, 30 December 2006 (UTC)

Re-add basic content: The famed "sentence from a week ago" (aka sentence -ve19) was re-added but with some minor wordiness reduction; and segmented into more than one sentence for easier readability and increased clarity to non-expert readers. HTH. dr.ef.tymac 05:00, 30 December 2006 (UTC)

Dreftymac: Thanks for helping to improve the current article rather than trying to start from scratch. I think an important distinction to make is that comments are primarily aimed at human readers while "program code" is aimed at computer "readers" of the source. The idea of using colors to help readers distinguish between comments and code is a good one, but a picture is the wrong approach. Why not include some code in a reduced font size (this may be hard to read, but I found the picture very hard to read) + colored to highlight various aspects. Derek farn 11:27, 30 December 2006 (UTC)

refinements to "comments are ignored"

(Note: Recently a participant in this forum took issue with the usage "comments are ignored". Although the issue was earlier dropped mid-topic, the issue was revisited and this separate thread was created to help keep major topics in the talk page separate and organized. --dreftymac) The following proposed clarification seems fine, except if the goal is exacting precision, then there are a few issues, some of which are enumerated below:

Comments are pieces of text interspersed in programs' source code for explanatory or documentation purposes.(1) Comments must be marked indicated in a way that allows a source code processor (interpreter or compiler)(2) to recognize them as such. so that no further syntactis and/or semantic analysis is performed on them.(3) This is often simplified by saying comments are "ignored" (after they have been recognized) by the processor.

• (1) The concepts this sentence are already conveyed in the article.
• (1) Comments include more than just text (see e.g., "audio comments" in article {also a rationale for changing "marked"})
• (2) This list is not exhaustive (e.g., omits source code filter, preprocessor, code formatter, and other related tools). The list should either be qualified to reflect this, or omitted to avoid the kind of imprecision this paragraph purports to correct.
• (3) For some programming languages, and in some contexts, not all comments are "ignored" (in the sense relevant here), so this clause is factually incorrect.
• The word "translator" was changed to the more encompassing term "processor".

In light of the above, I intend to put a modified version of the proposed refinement in a footnote. Feedback, further refinements, other relevant stuff are of course welcome. Thanks! dr.ef.tymac 17:10, 31 December 2006 (UTC)

How sad. This finally confirms what was my impression right from start: you don't know what you are talking about, sorry. (Unwatching these article and discussion pages for the foreseeable future). —Gennaro Prota^•Talk 18:31, 31 December 2006 (UTC)

Non-responsive response: Ok, second time for the "You're wrong, I'm right, goodbye." thing. No cites, no summary, you did not even specify a *single* flaw. Even if I were 100% hopelessly clueless, there are millions of other potential contributors to this article, you could have made a correction to benefit them. Even *I* know there's room for improvement in what I put up there ({e.g., "comments include more than just text" relies on admittedly broad definition of 'comment'} that's why I encouraged feedback and further refinements). Oh well, feedback is still welcome, hopefully we can keep it on the subject matter of the article when you come back. dr.ef.tymac 22:57, 31 December 2006 (UTC)

What bothers me a lot (apart from your pervasive use of bold) is that I propose an improvement here; you change it completely and edit the article. Then where is the discussion? I could have edited the article in the first place. As to your changes: my definition concerned the translator (compiler or interpreter); other processors (documentation extractors etc.) have to choose formats which are a particular form of those accepted by the source language translator. "Audio comments" which you seem to love so much are just paths/urls to audio files, so they are text in themselves (perhaps you could UUencode the audio file, but still...). Then again, I asked whether in "/* comment */" you considered comment or /* comment */ to be the comment, which you didn't reply to; that makes quite a difference for our definition. Then again, try this with a Java compiler

// here's a comment \uXXX

The compiler will _recognize_ it as a comment and emit an error. Why it doesn't "ignore" it? Everyone here should contribute to articles on topics they are knowledgeable about; are you realizing that you are doing harm? —Gennaro Prota^•Talk 08:54, 1 January 2007 (UTC)

Thanks for responding: I appreciate that you are including *specific relevant issues* now, instead of (solely) going off-topic with unsubstantiated, irrelevant, and incorrect guesses about general knowledge. dr.ef.tymac 17:39, 1 January 2007 (UTC)

Edit philosophy: We may be operating under different assumptions about what constitutes a sensible strategy for editing articles and working together. I am willing to discuss this to avoid unintended irritations and misunderstandings, but I think such discussion is better on a user talk page. dr.ef.tymac 17:39, 1 January 2007 (UTC)

Use of bold: I use bold, numbering, and threads to help keep the discussion on-topic, easily scannable and well-organized. If it truly bothers you, I welcome (constructive) suggestions for alternatives. I appreciate that different people have different communication styles. dr.ef.tymac 17:39, 1 January 2007 (UTC)

Source language translator: The point you were making there was not lost on me. The problem was, by introducing exacting precision on one issue, you were (potentially) introducting *new inaccuracies* on other issues. For example:

other processors (documentation extractors etc.) have to choose formats which are a particular form of those accepted by the source language translator. consistent with the language specification.

That's nice, except your original proposed refinement did not even acknowledge the existence of other types of processors. Moreover, you seem to be assuming "the source language translator" is some kind of monolithic, definitive authority rather than merely an implementation of what is *truly* authoritative: the language specification itself. What about language translators that do not fully conform to the specification? dr.ef.tymac 17:39, 1 January 2007 (UTC)

Audio comments: You mention nothing new nor not-already-known here. Of course it is just a text link. I already acknowledged that this a judgement-call based on how one defines "comment". I do however think it is a good thing that Wikipedia articles contain information that most people might not have otherwise discovered, as long as it is not spam/advertising/cruft, which this does not appear to be. The point is simply to make sure the article is internally consistent. dr.ef.tymac 17:39, 1 January 2007 (UTC)

Unicode escape sequences and comment definition: Not only did I reply to your bit about the definition of "comment" I created a separate thread to discuss the issue. You'll notice there that I rely on *citable authority* (language specifications) as the basis for the first part of the definition. Your issue about processing unicode escape sequences is already documented in the java language specification (see e.g., Chapter 3). The non-sequitur about general knowledge is not only irrelevant, it ignores the central importance of (say it with me) Wikipedia:Verifiability. dr.ef.tymac 17:39, 1 January 2007 (UTC)

The phrase "comments are ignored" is a good sound-bite that gives readers a quick overview of what comments are about. Unfortunately it is technically incorrect in that compilers do have to process them to ignore them. So what we need is a phrase that gives a readers a quick overview of the subject and is technically correct. How about something along the lines of "Comments contain information that may be of use to people reading source code, however this information is generally ignored by compilers...". We also ought to point out that "Comments are generally part of the lexical syntax of a programming language and have to be processed by compilers in the sense that their contents have to be skipped." Derek farn 17:04, 1 January 2007 (UTC)

Replace "ignored" with "discarded": Any objections to that as a fix for the current intro text? Seems like a very easy resolution and it does not alter the readability. dr.ef.tymac 05:16, 2 January 2007 (UTC)

Dreftymac I don't dislike discarded. Trouble is all sorts of other constructs can be said to be discarded, eg, local declarations once a compiler has finished processing a function. Derek farn 10:10, 2 January 2007 (UTC)

That doesn't invalidate the accuracy of the statement though does it? The text doesn't say "it is both necessary and sufficient to call X a comment if it is discarded". It just says comments are (generally) discarded. How is it even possible to write a generally accessible article introduction if accurate-yet-not-categorically-exhaustive statements are completely forbidden, especially since clarifying footnotes are always available to satisfy more "fastidious" readers? dr.ef.tymac 12:45, 2 January 2007 (UTC)

I am not for or against the change. I'm just pointing out that, like ignored, there are ways of reading discarded that suggest unintended meanings. Derek farn 13:58, 2 January 2007 (UTC)

Back to square zero - just leave it as is: Since this issue was previously dropped mid-topic; and since the only (cited) proposed phrasing for "introductory style text" was "comments are ignored"; and since the only provided rationale for opposing this phrasing was 1) you dont know what you are talking about; and 2) the phrasing occurs where one just tries to "get started"; and 3) it is technically inaccurate; and since this article is supposed to be accessible to a general audience (some of whom are indeed at 'tutorial level' understanding); and since the technically inaccurate text is already qualified with a clarifying footnote; and since the English language is replete with phrasings that are "technically inaccurate" and yet nonetheless widely accepted for sake of conciseness (e.g. the "Sun rises in the East and sets in the West"); I propose either: i) the text be left as is; ii) someone else provide a *cited* alternate phrasing that conveys the same idea and still keeps the intro readable and accessible; or iii) someone credibly explain why "introductory level text" is not appropriate for an "introductory level article paragraph". dr.ef.tymac 16:06, 2 January 2007 (UTC)

refinements to definition of "comment"

I have been operating under the view that (for purposes of this article) "Comment" is a compound definition with more than one sense: 1) the lexical conventions as defined in a formal language specification for indicating comments as sub-regions of source code; 2) the notes, reminders, docs and other linguistic artifacts indicated inside those subregions; and 3) any of various other recognized conventions (either present or future) that legitimately merit discussion in this specific article. So far, I haven't noticed anything in the article that is inconsistent with this view. Nor does this view seem unreasonable. Thoughts? Comments? dr.ef.tymac 17:22, 31 December 2006 (UTC)

Follow-up: Definition 2) above was intended to include text-based cross-references to external binary resources (such as an audio file). This is an admittedly broader definition than some might expect, but seemed worth considering in light of some of the article content. dr.ef.tymac 23:06, 31 December 2006 (UTC)

Hello everybody? I would like to ask wether comeents in c are better or in Ada ? why?