| Home | Notes | Languages | Programs | Homework |
Re: Question about comments for CS 3304 Pascal program |
Stephen Edwards (edwards@CS.VT.EDU)
Mon, 19 Feb 2001 09:01:55 -0500
Message-ID: <3A912753.6D649D0@cs.vt.edu> Date: Mon, 19 Feb 2001 09:01:55 -0500 From: Stephen Edwards <edwards@CS.VT.EDU> Subject: Re: Question about comments for CS 3304 Pascal program
Alicia Baturay wrote:
> I understand the purpose, but is the calling sequence which function calls
> it?
No, it is which other functions it depends on (i.e., what is it built
on top of?). A full description of the "calling sequence" (which is
really all the information you'd see in a structure chart or call
graph) is not necessary.
> And I do
> not know what you mean by implementation.
A description of the algorithm used, or how the the subroutine achieves
its goals. For recursive descent parsing operations, just including the
grammar rule it embodies in a comment is usually enough, although any
deviations from the rule should be documented.
The main thing here is to document any conventions or expectations your
function/procedure has, which can affect how it interacts with other
operations. In our case, the info that isn't captured in the grammar
rule for a nonterminal but that is important for your procedures/functions
includes things like:
+ Does the operation "use up" or advance the current token?
+ What information does your operation add to your intermediate
representation?
+ How are error conditions handled by your operation?
There are probably others, but these cover the bases. These are the
kinds of details that should be highlighted in comments, rather than
buried in the details of the code itself.
-- Steve
-- Stephen Edwards 604 McBryde Hall Dept. of Computer Science e-mail : edwards@cs.vt.edu U.S. mail: Virginia Tech (VPI&SU) office phone: (540)-231-5723 Blacksburg, VA 24061-0106 -------------------------------------------------------------------------------
| Home | Notes | Languages | Programs | Homework |