Talk:Comment (computer programming): Difference between revisions

Revision as of 07:53, 27 December 2013

Latest revision as of 12:29, 11 January 2025

(19 intermediate revisions by 15 users not shown)

Line 14:

|topic=Engtech

}}

{{WikiProject Javabanner shell|class=B|importance=low}}

{{WikiProject Computing|class=BJava|importance=highlow}}

{{WikiProject Computing|importance=high}}

}}

== article move ==

Line 45 ⟶ 48:

::::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., [[John_Seigenthaler_Sr._Wikipedia_biography_controversy|here]] for a well-known example) if that was the point being made, I will dismiss it as incorrect and irrelevant, if that was notwasn't the point, please clarify. [[User:Dreftymac|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! [[User:Dreftymac|dr.ef.tymac]] 15:57, 29 December 2006 (UTC)

Line 52 ⟶ 55:

:: '''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. [[User:Dreftymac|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". [[User:Dreftymac|dr.ef.tymac]] 16:11, 29 December 2006 (UTC)

::::Layer [[Special:Contributions/2603:8000:A200:D9F8:4195:9490:1C9D:7DF7|2603:8000:A200:D9F8:4195:9490:1C9D:7DF7]] ([[User talk:2603:8000:A200:D9F8:4195:9490:1C9D:7DF7|talk]]) 07:33, 2 October 2023 (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's hardly a straightforward way of providing an introduction to the term. [[User:Derek farn|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. [[User:Dreftymac|dr.ef.tymac]] 18:27, 29 December 2006 (UTC)

Line 71 ⟶ 75:

| publisher = Computer Bks / Languages/ Programming

| year = 2004

| id = {{ISBN |1852337680}}

}}</ref>) '''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? [[User:Dreftymac|dr.ef.tymac]] 11:43, 29 December 2006 (UTC)

Line 85 ⟶ 89:

: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. [[User:Derek farn|Derek farn]] 14:19, 29 December 2006 (UTC)

{{reflist-talk}}

== text from a week ago ==

Line 110 ⟶ 116:

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:

<div style="border:1px solid black;">

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

</div>

* <fontspan colorstyle="color:red;">(1)</fontspan> The concepts this sentence are already conveyed in the article.

* <fontspan colorstyle="color:red;">(1)</fontspan> Comments include more than just text (see e.g., "audio comments" in article {also a rationale for changing "marked"})

* <fontspan colorstyle="color:red;">(2)</fontspan> 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.

* <fontspan colorstyle="color:red;">(3)</fontspan> 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! [[User:Dreftymac|dr.ef.tymac]] 17:10, 31 December 2006 (UTC)

Line 137 ⟶ 143:

:::'''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:

<div style="border:1px solid black;">

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

</div>

:::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? [[User:Dreftymac|dr.ef.tymac]] 17:39, 1 January 2007 (UTC)

Line 151 ⟶ 157:

::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? [[User:Dreftymac|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. [[User:Derek farn|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 <strikes>1) you dont know what you are talking about;</strikes> 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". [[User:Dreftymac|dr.ef.tymac]] 16:06, 2 January 2007 (UTC)

== refinements to definition of "comment" ==

Line 175 ⟶ 181:

Please address these matters soon and then leave a note here showing how they have been resolved. After 48 hours the article should be [[Wikipedia:Good article candidates|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.<!-- Template:FGAN -->

— [[User_talk:Giggy|<fontspan colorstyle="color:green;">'''Giggy'''</fontspan>]] _{[[User:Giggy|<fontspan colorstyle="color:red;">U</fontspan>]]}^{[[User:Giggy/Contribs|<fontspan colorstyle="color:orange;">C</fontspan>]]}[[WP:FING|P]] 03:43, 24 July 2007 (UTC)

:''Version reviewed (for my reference):'' [http://en.wikipedia.org/w/index.php?title=Comment_%28computer_programming%29&oldid=146680882]

Line 205 ⟶ 211:

: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. [[User:Dreftymac|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! [[User_talk:Giggy|<fontspan colorstyle="color:green;">'''Giggy'''</fontspan>]] _{[[User:Giggy|<fontspan colorstyle="color:red;">U</fontspan>]]}^{[[User:Giggy/Contribs|<fontspan colorstyle="color:orange;">C</fontspan>]]}[[WP:FING|P]] 23:50, 24 July 2007 (UTC)

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

Line 216 ⟶ 222:

: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:

<syntaxhighlight>

<code>

frame.pack();

frame.show(); // display the fra

}

</syntaxhighlight>

</code>

:when it should read

<syntaxhighlight>

<code>

frame.pack();

frame.show(); // display the frame

}

</syntaxhighlight>

</code>

: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. --[[User:Quuxplusone|Quuxplusone]] 02:20, 10 August 2007 (UTC)

Line 240 ⟶ 246:

*I strongly support the merger proposal. --[[User:Malleus Fatuorum|Malleus]] [[User_talk:Malleus_Fatuorum|Fatuorum]] 22:01, 4 December 2008 (UTC)

*'''Strong support'''. Is there a speedy redirect procedure? [[User:TheFeds|<fontb style="font-family:Constantia"; font-size="3":medium; color=":#0077bb;">[[User:TheFeds|'''''TheFeds''''']]</fontb>]] 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:

Line 290 ⟶ 296:

The PHP sample section says, "Comments in PHP can be either in C++ style (both inline and block), or use hashes." and yet there is no example of the comment style of C++. If it is the same as "C", then the reference should be changed, although the "C" example only has one style of commenting illustrated, so the "(both inline and block)" reference would be unclear. [[Special:Contributions/208.81.28.204|208.81.28.204]] ([[User talk:208.81.28.204|talk]]) 13:57, 15 February 2013 (UTC)

== Replacing the "Examples" section wihtwith a table==

I think this article would be better suited by a table and brief explanation, below, describing the various commenting styles rather than the extensive examples sections:

Line 346 ⟶ 352:

Which language specification first introduced code comments? I know they date back to the sixties with [[BCPL]], [[COBOL]], [[ALGOL 60]] and [[BASIC]]. So a better question might be, when did comments first appear in an [[assembly language]]..? <span style="font-variant:small-caps">[[User:John Vandenberg|John Vandenberg]] ^{'''([[User talk:John Vandenberg|chat]])'''}</span> 07:53, 27 December 2013 (UTC)

== SGML comments ==

Comments in documents, most notably SGML comments, from which [[HTML comment]] and [[XML comment]] are derived, are an important part of the 'Comment' concept. However this page is titles 'Comment (computer programming)', and comments in documents are not computer programming. But, [[XSLT]] (and similar) is a functional programming language. And [[Windows Script File]] & [[ColdFusion]], already mentioned in this page, introduce SGML comments without explaining them properly. Should 'document comments' be part of this page, or be a separate page. If included in this page, the intro and/or title of this page needs to be more inclusive. <span style="font-variant:small-caps">[[User:John Vandenberg|John Vandenberg]] ^{'''([[User talk:John Vandenberg|chat]])'''}</span> 08:28, 27 December 2013 (UTC)

==Fortran IV==

Have deleted the recently-added second example. While chock full of interesting stuff, it added nothing new about ''comments'' - and mentioning [[ASCII]] is "interesting"... [[User:Snori|Snori]] ([[User talk:Snori|talk]]) 19:53, 7 April 2017 (UTC)

== External links modified ==

Hello fellow Wikipedians,

I have just modified one external link on [[Comment (computer programming)]]. Please take a moment to review [https://en.wikipedia.org/w/index.php?diff=prev&oldid=794985206 my edit]. If you have any questions, or need the bot to ignore the links, or the page altogether, please visit [[User:Cyberpower678/FaQs#InternetArchiveBot|this simple FaQ]] for additional information. I made the following changes:

*Added archive https://web.archive.org/web/20070722211609/http://www.ptlogica.com/TwinText/resource/liveuser.pdf to http://www.ptlogica.com/TwinText/resource/liveuser.pdf

When you have finished reviewing my changes, you may follow the instructions on the template below to fix any issues with the URLs.

{{sourcecheck|checked=false|needhelp=}}

Cheers.—[[User:InternetArchiveBot|'''<span style="color:darkgrey;font-family:monospace">InternetArchiveBot</span>''']] <span style="color:green;font-family:Rockwell">([[User talk:InternetArchiveBot|Report bug]])</span> 07:58, 11 August 2017 (UTC)

== Merge proposal from article "Docblock" ==

So there's this article titled [[Docblock]] which I think is not notable enough to have its own article and should be merged into here (more specifically, [[Comment_(computer_programming)#Automatic documentation generation]]) [[User:Bctnry|Bctnry]] ([[User talk:Bctnry|talk]]) 23:32, 26 July 2024 (UTC)

:Nothing heard (and I agree) so I performed the merge. -- [[User:Mikeblas|mikeblas]] ([[User talk:Mikeblas|talk]]) 01:52, 9 September 2024 (UTC)

== Off the mark in a few places ==

WRT current open: "In computer programming, a comment is a human-readable explanation or annotation in the source code of a computer program" all source code should be human-readable; not just comments. I think the point is that a comment is gibberish to the computer, yet meaningful to a human. So, "human-readable" is not wrong when describing a comment, but it's misleading since saying that implies that some adjacent concept is not human-readable. And the most adjacent concept is the non-comment code.

WRT short desc: "Explanatory note in the source code of a computer program" A comment is does not necessarily explain something. The content of a comment could be nonsensical or gibberish; yet it's still a comment. A comment is simply text embedded in source code that the translator (i.e. compiler) ignores. Often it explans something, but to say a comment is explanatory is an overreach.

To say that a comment is in source code of ''a computer program'' is overstating as well. I can write a code fragment with a comment, and IMO that's still a comment. A comment need not be part of any computer program to still be a comment.

In general, this article is written in touchy-feely wording that is close to being right and covers typical scenarios. But, it's not accurate. IMO, it should be both accurate and describe common scenarios/uses. [[User:Stevebroshar|Stevebroshar]] ([[User talk:Stevebroshar|talk]]) 11:25, 9 January 2025 (UTC)

:I edited the article relatively heavily to address these issues. [[User:Stevebroshar|Stevebroshar]] ([[User talk:Stevebroshar|talk]]) 12:29, 11 January 2025 (UTC)