| 
|
Topic: comments
topics >
computer science >
programming >
literate programming
Topic:
program listing
Topic:
programming style
Topic:
sections of a program
Topic:
software documentation
Summary
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: indicating comments
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: comment conventions
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: avoiding comments
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: annotation comments
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]
Quote: flavor analysis comments on an existing program were similar to the original comments
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)