From the Computer Science 50 web site:
Comments are essential to readable code. Comments should
appear at the beginning of every file (called file header
comments), at any piece of code that is tricky to understand,
and at most variable declarations. Note that this is _not_
a comprehensive list. Comments belong anywhere they will
improve the readability and understandability of your code.
However, there is such a thing as over-commenting. Remember that the
goal is improved readability.
...
Each function definition should be preceded by a block comment that
includes the function name and a short description of what the
function is supposed to do. Also in the function header should be a
description of the inputs (parameters) and the output (return value).
It is also a good idea to state if global variables are modified
inside the function, and any other external state changes, such as
reading, writing or freeing...
Charles
On Mon, 24 Mar 2003, Olivia Lau wrote:
Dear all,
I was wondering, are there rules for commenting programs? Does
someone know of a good example of a well-documented program that
could be distributed to the list? For example, what information
is supposed to go at the head of the program? Also, for the
purposes of this assignment, should we include all of our R code
in one long file or break up the functions into little files?
Thanks,
Olivia
_______________________________________________
gov2001-l mailing list
gov2001-l(a)fas.harvard.edu
http://www.fas.harvard.edu/mailman/listinfo/gov2001-l