>
>> I personally like flowcharts better than commenting
>
> In my opinion, flowcharts are useful in two ways:
> 1. As an aid to help create the project story.

Yah; that's about my opinion; flowcharts aren't so much a competitor  
of COMMENTS as a competitor or component of SPECIFICATIONS.

In theory, we use a hierarchy of documentation:
1) Functional specification.  What it's supposed to do; the "marketing  
view."
   2) Design specification.  How it's supposed to do it.
     3) Code comments.  How it IS doing it.  Usually divided into those
	largish "subroutine" descriptions, and the smaller inline comments
	covering the details.
       4) "self documenting code."  Having 1-3 is no excuse for single
	  character variable names...

(If you think COMMENTS get out-of-sync with the actual code, you  
should see how badly the specifications become out-of-date!  The  
specifications are typically needed prerequisites for the overall  
software development process, and it is unfortunately REALLY RARE for  
anyone to update the specs after that phase of approval is over.  Sigh.)

(I hardly ever do functional or design specs for "personal" project,  
although it seems like it would be a good idea.  If I'm lucky,  
something similar might get written up AFTER the coding, as a sort of  
step toward publication...  Sigh, again.)

(So with all these new-style "development environment", do ANY of them  
aid in keeping high-level formatted documentation (HTML, RTF, WORD,  
whatever) in sync with the actual code?  I mean, I can hover a cursor  
over a preprocessor symbol and see its definition, or over a  
subroutine call and see its header-comment; right?  Shouldn't there be  
some standardized method of associating a region of code with a subset  
of a design document or functional description, so that a single  
keyclick reminds me what I'm supposed to be doing and how, and allows  
me to edit it if I've changed my mind?  URL tags in source code; how  
hard can it be?  Sometimes the failings of software design and  
implementation have more to do with those mis-matches between high- 
level descriptions and source code, regardless of how well written (or  
not) the source code itself is.  Sigh, a third time.)

In other words, documenting the "project" is at least as important as  
documenting "the code."  And is much more often neglected...  (flow  
charts (remember flow charts, this is a reply to a message about flow  
charts!) are nicely intermediate...)

BillW

-- 
http://www.piclist.com PIC/SX FAQ & list archive
View/change your membership options at
http://mailman.mit.edu/mailman/listinfo/piclist