comment

n 1: a statement that expresses a personal opinion or belief;

"from time to time she contributed a personal comment on

his account" [syn: {remark}]

2: a written explanation or criticism or illustration that is

added to a book or other textual material; "he wrote an

extended comment on the proposal" [syn: {commentary}]

3: a report (often malicious) about the doings of other people;

"the divorce caused much gossip" [syn: {gossip}, {scuttlebutt}]

v 1: make or write comment to make a comment on [syn: {notice}, {remark},

{point out}]

2: explain or interpret something

3: provide interlinear explanations for words or phrases [syn:

{gloss}]

comment

(Or "remark") Explanatory text embedded in

program {source} (or less often data) intended to help human

readers understand it.

Code completely without comments is often hard to read, but

too heavily commented code isn't much better, especially if

the comments are not kept up-to-date with changes to the code.

Too much commenting may mean that the code is

over-complicated. A good rule is to comment everything that

needs it but write code that doesn't need much of it.

A particularly irksome form of over-commenting explains

exactly what each statement does, even when it is obvious to

any reasonably competant programmer, e.g.

/▫ Open the input file ▫/

infd ◦ open(input_file, O_RDONLY);

(1998-04-28)