On 4/20/2011 11:33, Alain wrote:
> Le 2011/04/20 14:23, Darren New a écrit :
>> On 4/20/2011 10:37, Alain wrote:
>>> Comments, comments, comments and more comments.
>>> That's the only way that code can be used as documentation.
>>
>> Yep. And that assumes you know the right place to look in the code to
>> find the documentation. Without an overview, you wind up guessing whic
h
>> source files of which subdirectories you need to read for comments.
>>
>
> You start the main with a big comment block that contains an exaustive
> overview of the project. It's then followed by a table of content and a
n
> index...
>
> Then, each individual source files also contains a specific overview of
 the
> function(s) of the following code, what kind of data it expect and what
 kind
> of data it's expected to return. Don't forget the local table of conten
t and
> index.

I'm at a loss as to why such would be in comments in source code, but OK.
 :-)

-- 
Darren New, San Diego CA, USA (PST)
   "Coding without comments is like
    driving without turn signals."

Post a reply to this message