Bob Axtell wrote:
>I personally like flowcharts better than commenting, because
> if the program is to be rewritten, the author has a choice of
> languages to use.
>
> What happens is that a company has a great programmer that
> did a fine job. Say he did his work in MPASM. Now that guy
> retires (or moves because his wife, a doctor, makes the REAL
> bucks in the family) and it is almost impossible to find someone
> that writes MPASM to replace him.
>
> See what I mean? Flowcharts beat the TAR out of comments, every
> day of the week.


Flowcharts are great, in theory. :-)

I believe it is Alistair Cockburn who argues in his book, that project 
documentation cannot replace what's called a "project story" (a common 
understating/vision of the project), because human communication is so 
imperfect. A project story resides in the programmer or the team of 
programmers who work on the project. One of the implications is that you 
cannot take documentation, however perfect, throw it over the wall, and 
expect another team to pick up where the old team left off without missing a 
beat: they must first develop their own project story. Another implication 
is that the value of documentation tends to be overrated.

Flowcharts share many of the same problems with comments. Probably the 
biggest problem is that they both get out of sync with the code. Flowcharts 
are even more vulnerable in this regard: it's easier to update a comment, 
than a flowchart.

In the past, I used to create complex flowcharts. They were necessary 
because I simply could not hold all the details of the huge state machines 
in my head. Today, I no longer find them necessary -- instead, I write ten 
small functions, in place of one very long one. The state machine then 
easily fits in one screenful of code (a single function).

In my opinion, flowcharts are useful in two ways:

1. As an aid to help create the project story. The process of creating the 
flowchart is the valuable part, not the end result.

2. In situations where you are forced to write ugly code due to the 
limitations of the target hardware (can't afford the extra overhead of 
function calls, must code in assembly, etc).

Best regards,

Vitaliy 

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