UNBCIC@BRFAPESP.BITNET (05/21/91)
=> From: john wavrik <sdcc6!ir230@UCSD.EDU>
=> Subject: RE: Modular coding style
=> The problem of where to put comments is a fascinating one. We've tried
=> several alteratives (both in research work and in teaching). Including
=> a great amount of comments in the source code has proven to have a
=> self-defeating effect: the comments hide the code and actually make it
=> harder to read. For research we have found that, in addition to the
=> modules, individual words often become important in future work -- so
=> a separate glossary (in the form of a database) is used to describe
=> words and indicate their location in source code files. For
=> instruction, students are encouraged to describe the intended function
=> of words in a separate place in the source code (e.g. above the
=> definition itself) and restrict commenting within a definition to
=> stack diagrams or brief comments which help a reader understand the
=> code. [Neither of these practices are firm -- but they seem to be the
=> best so far.]
That's what I like in F-PC. With its Hypertext system I can swap from the
source file, with the definition of the word and comments on (IMPORTANT!) HOW
IT WORKS to and help file, with the comments on WHAT IT IS USED FOR. Both are
text files, and you don't need to search on the file for the line where the
information starts.
(8-DCS)
Daniel C. Sobral
UNBCIC@BRFAPESP.BITNET