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)

Styles: "visibility"

In the section on Style, the following statement should be supported by a reference: "On the other hand, the visibility of the second comment variant is much higher." According to whom? Even if this statement appears to the author(s) to be true, "visibility" isn't defined within the article. -24.128.160.83 15:29, 15 March 2007 (UTC)

I doubt if any such reference exists. A while back I researched what experimental evidence there was for various readability issues in programming. The answer was very close to zero. Anyway before we can do relative comparisons on visibility the term has to be defined. How exactly is visibility to be measured? Derek farn 16:58, 15 March 2007 (UTC)

Good article nomination on hold

This article's Good Article promotion has been put on hold. During review, some issues were discovered that can be resolved without a major re-write. This is how the article, as of July 24, 2007, compares against the six good article criteria:

1. Well written?: In most cases, when the source code is processed by a compiler or interpreter, comments are ignored. - Last time I checked, comments are always ignored by the interpreter. The "in most cases" isn't true IMO.
You need to discuss the Philosophy section in the lead.
In the 2nd paragraph of the overview section, you have about 3 sentences in a row that start with "Block comments..." Reword?
as described previously in this article. - This isn't really necessary. People can look around if they need more info.
or maybe this - Too informal
At least one commentator[14] advocates aligning the left edges of comments: - Include his name here, you only ref his statement (hence place ref at end of statement).
This section needs wikilinking (to the respective languages)

2. Factually accurate?: More internet references would be useful (since we don't want to run off to the library every time we read an article!)
This is called the why rather than how approach. - Who said it is?
Do we have a ref or example for this section?
Some contend that comments are unnecessary because well-written source should be self explanatory; others contend that source code should be extensively commented - Ref for people saying these things?

3. Broad in coverage?: Y

4. Neutral point of view?: Y

5. Article stability? Y

6. Images?: Y

Please address these matters soon and then leave a note here showing how they have been resolved. After 48 hours the article should be reviewed again. If these issues are not addressed within 7 days, the article may be failed without further notice. Thank you for your work so far. — Giggy _U^CP 03:43, 24 July 2007 (UTC)

Version reviewed (for my reference): [1]

Initial response

First off, thanks very much for taking the time to review this article, and for your suggestions. All of the remarks make sense, and I am confident that the issues can be resolved within a few days, barring any additional difficulties. One or two points may necessitate some clarification based on the edit history and past items from article discussion, so I will make an effort to organize those (if and when appropriate), for fast and easy review.

For the rest, I plan to take responsibility for these improvements and will make the necessary adjustments directly to the article as time permits. Thanks again for your critique and recommendations! Regards. dr.ef.tymac 10:06, 24 July 2007 (UTC)

ISSUES TO ADDRESS:

• wikilink languages  ;; Y (done) added links and short descriptions to the "in context" examples
• at least one commentator ;; Y (done) removed
• more web references  ;; Y (done -- but ongoing) added some more web links, a few more could go in to support the books but need good ones
• "or maybe this"  ;; Y (done) removed and cleaned up somewhat informal tone
• as described previously  ;; Y (done) removed
• rw redundant "block comments" ;; Y (done) reworded and wikify
• philosophy section lead coverage ;; Y (done) added lead-in to philosophy and guidelines
• "in most cases"  ;; (unchanged) There's an issue with this that I will address below.
• "why rather than how"  ;; Y (done) remove as I don't think this was ever referenced to begin with
• resource inclusion (refs and examples) ;; Y (done) added refs and code example, also added counter-example contrasting alternatives to use of comments
• extensively commented vs self explanatory (refs) ;; Y (done) added refs substantiating the "some say" claims

(prelim_review001). dr.ef.tymac 10:17, 24 July 2007 (UTC)

O.k. I've taken a first-stab completion at all the items on the list ... all of them except for "in most cases" from the lead section. This was introduced to the article text after some laborious discussion for two main reasons (to the best of my interpretation and understanding):

• 1) not all "comments" in source code are "ignored" (according to the traditional understanding of "ignored"). For example, Plain Old Documentation in perl is sometimes classified as that language's equivalent of "multiline" or "block" comments. (See e.g., here).
• 2) the "traditional understanding" of "comments are ignored" is subject to some dispute, and technically "imprecise" (as was debated on this talk page) see here. I'm not sure you can say there was a clear consensus conclusion here; but given the underlying technicalities, it is technically not correct to say that "all" comments are "ignored" ... and also not technically correct to say that "some" comments are always "ignored".

Because of this issue, and because other participants to this article may want to put in their two cents on this, I will refrain from modifying this part of the article.

All of the other points in the GAC review I've attempted to address and should now be fairly represented in the article itself. Regards. dr.ef.tymac 17:29, 24 July 2007 (UTC)

The "comments are always ignored" thing was just based on my (limited) programming experience (with HTML and VB, if you must know). Your response seems correct (it would be nice if this was discussed somewhere in the article!), and everything else has been addressed, so I'm passing it now. Congratulations! Giggy _U^CP 23:50, 24 July 2007 (UTC)

O.k. Thanks again for the review, and for the many helpful remarks -- much appreciated! dr.ef.tymac 04:49, 25 July 2007 (UTC)

Image suggestions

I think the image would be better if it looked like it were from some programmers' editor, maybe with only the comments colored/highlighted (and colored with a single color, instead of two). Currently the thing that draws attention in it is not the comments but the curled corner effect (which no editor I've seen uses), and as the distinction between prologue and inline comments is not mentioned in the introduction, it would be clearer not to distinguish them in the image. -- Coffee2theorems 01:04, 10 August 2007 (UTC)

What is the "curled corner effect"? The only thing weird about the current image that I noticed was that the last line of code (before the closing brace) is mis-indented and the associated comment is truncated:

    frame.pack();
   frame.show(); // display the fra
   }

when it should read

    frame.pack();
    frame.show(); // display the frame
   }

It might be an SVG bug, though. In any event, IMHO there's no real reason to have an image on this article anyway; it just shows the same thing the code samples show, but in a less reader-friendly fashion. --Quuxplusone 02:20, 10 August 2007 (UTC)

Line comments

Needs to be some differentiation between two ways these work: Either (a) delimiter can *only* is the first no-white-space and the whole line is a comment (ie oldskool BASIC); or (b) the the delimiter can also be used to the right of an executable line of code. Also, it's not clear what's so special about the "End-of-line comment" - why does this deserve it's own section? Snori (talk) 08:16, 12 August 2008 (UTC)updating articl

Good Article review

Pursuant to the comments made under the Engineering and technology good articles review and de-listing. I have initiated some modifications to this article in order to address the relevant issues addressed there. Please consult the remarks at [2] and leave a comment here if you would like to modify the article as well, as it will help to ensure changes are compatible, complementary, and consistent with the goal of re-listing the article as a Good Article. Thanks. dr.ef.tymac (talk) 19:55, 4 December 2008 (UTC)

Merge proposal

• I strongly support the merger proposal. --Malleus Fatuorum 22:01, 4 December 2008 (UTC)
• Strong support. Is there a speedy redirect procedure? TheFeds 05:50, 27 January 2009 (UTC)

Merge process completed. However, there was some text I wasn't able to integrate to this article. It appears below:

---

Another common usage are the comments that appear in an initialization or configuration file.

Word processors often support an feature that enables writers of documents to effectively write private notes to themselves about the material they are writing. These notes are not visible to a reader of the document unless explicitly asked for.

---

I have put this excerpt here in the case you find some way to add it (with the required adaptations) to this article or to another article. This is preservable information; it would be a pity not to be able to integrate it somewhere. --Antonielly (talk) 13:49, 4 March 2009 (UTC)

 Done. This information is now in the comment article. --68.0.124.33 (talk) 16:36, 22 July 2009 (UTC)

Uses of comments

I'm missing the use of comments to add code in a forward compatible fashion, e. g. IE conditional comments. 78.52.101.8 (talk) 09:41, 7 July 2010 (UTC)