piclist 2008\10\20\034024a >
Thread: Self documenting code vs. Comments
face BY : Vitaliy email (remove spam text)

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,


<098901c93287$08e4dcc0$6f02a8c0@ws11> 7bit

See also: www.piclist.com/techref/index.htm?key=self+documenting
Reply You must be a member of the piclist mailing list (not only a www.piclist.com member) to post to the piclist. This form requires JavaScript and a browser/email client that can handle form mailto: posts.
Subject (change) Self documenting code vs. Comments

month overview.

new search...