Topic: comments

topics > computer science > programming > Group: programming notation

literate programming
program listing
programming style
sections of a program
software documentation


Comments allow the user to provide additional documentation for a program. Their use is largely determined by individual style. No comments indicates hard to read text while a comment on every line is overly verbose. Comments tend to re-word a program in an alternative language. For instance a pseudo language is used for high level languages. A limitation of comments is the lack of correctness guarantees, especially in frequently modified programs.

Comments need to be separated from normal text. Options are character comment flags, column comment flags, comment termination by end-of-line, comment defined columns, comment defined lines, and noise words without syntactic meaning. Bracketed comment notations are sensitive to dropped closing brackets. A general problem with comments is defining their scope. This is overcome by defining comments for procedure headers which modify the entire procedure, or by using different comment types for different program levels. (cbb 5/80)

Subtopic: why comments up

Quote: programming improved by indentation, comments, mnemonic names; but not by structured programming [»pariG_1980]
Quote: comments should be one level of abstraction above the code [»shneB_1985]
Quote: while comments may be incorrect they still provide useful information about program history and quality [»weisM11_1987]
Quote: a comment should be used for each file, class, template, nontrivial function, global variable, exceptional code, and very little else [»stroB_1991]

Subtopic: indicating comments up

Quote: the scope of conventional comment statements is ill-defined [»wittRW9_1977]
Quote: Smalltalk comments are strings delimitated by double quotes [»xlrg8_1981]
Quote: C's comment convention does not work well; e.g., do not nest [»ritcDM7_1978c]
Quote: a better comment convention is comments from a unique character to the end of line [»ritcDM7_1978c]
Quote: assembly programming uses simple conventions for comments; conventions for programming languages may be error-prone [»hoarCA_1974]
Quote: treat comments as an unparsed syntax element; associate line comments with previous element [»mcarG10_2002]
QuoteRef: dod12_1977 ;;42 embedded comments terminated by end-of-line or end of comment symbol
QuoteRef: dod12_1977 ;;42 stand alone comments indicated by special character at beginning of line
QuoteRef: sammJE_1969 ;;268 material typed in red for comments

Subtopic: comment conventions up

QuoteRef: simscrip_1971 ;;138 Last column is ... any chars beyond are comments
QuoteRef: simscrip_1971 ;;57 Simscript uses ''comment_string
QuoteRef: sammJE_1969 ;;269 anything not syntactical defined is a comment
QuoteRef: hogbD10_1971 ;;3 command format: key-word number-list (any other interspersed symbols for documentation ok)

Subtopic: avoiding comments up

Quote: if possible, use the programming language instead of writing a comment [»stroB_1991]
Quote: instead of comments, use definitional text that defines the code to be written [»lingRC6_1975]
Quote: definitional text should be a line of text, maybe two; encourages effective abstraction [»lingRC6_1975]
Quote: use definitional text to enforce comment generation and to sharpen the intent and meaning for comments [»lingRC6_1975]
Quote: give every data object a data definition; precede program parts with action definitions and follow them with status definitions [»lingRC6_1975]

Subtopic: annotation comments up

Quote: flavor analysis comments on an existing program were similar to the original comments

Related Topics up

Topic: literate programming (16 items)
Topic: program listing (14 items)
Topic: programming style (47 items)
Topic: sections of a program (9 items)
Topic: software documentation
(64 items)

Updated barberCB 4/04
Copyright © 2002-2008 by C. Bradford Barber. All rights reserved.
Thesa is a trademark of C. Bradford Barber.