The ideal program, in the ideal programming language, would have no comments at all: Comments exist to convey important information about a program which cannot be expressed in the programming language itself, and the ideal programming language would be powerful enough to express all important information about the program. If the information is important, the compiler has just as much right to be told as does the human reader. As compilers evolve into true software environments, those environments will exhibit a steadily increasing appetite for all available information about the programs they are massaging.
We are today amazingly far from that ideal!
It is kind of neat watching the very first iron nails being painfully hand-forged by first-generation blacksmiths, even if at times one grows a little impatient for the era of mass-produced, reliable nails ...
In the present, while we await a brighter future, we are left hiding much of the content of our programs from our compilers in the form of comment statements for human consumption only.
Effective written communication with humans is not an altogether new art: Study of effective string composition and layout long precedes Gutenberg, extending in unbroken tradition back to Homer and beyond. Modern books, magazines, and printed matter generally are heir to millenia of hard-won expertise.
Even in our primitive ASCII era, much of this expertise can be applied to making programs easier and more pleasant to read; As programming emerges from the dark ages, we as programmers shall have access to steadily more of the resources that other writers take for granted, from font selection to illustrations.
I am utterly mystified why so many programmers seem to take obscure pride in writing program comments in utterly illiterate style, markedly below even their own habitual prose standards. For example, a capital letter at the start of a sentence, and appropriate punctuation at the end, make a sentence easier for the reader to pick out. This has been known for centuries, and hardly ceases to be true if the sentence happens to reside in a program instead of an essay. Why, then, do we see so many program comments lacking even such basic amenities?
Anyhow. For those who take pride in their programs, English style guides are there for the reading.
Go to the first, previous, next, last section, table of contents.