[Pdx-pm] documenting spaghetti code

[alan]

On Wed, 27 Jun 2007, Selena Deckelmann wrote:

> Hello,
>
> Apologies if this is a really dumb question.
>
> I have some really horrific code (in C) that I need to make a few
> changes to. Unfortunately, I must learn how most of the code works
> before I make the changes. There are about 20k lines, there is no
> test suite and the code is largely undocumented.
>
> I'm also working with some engineers who are not programmers, but
> need to know how the software works in order to make intelligent
> suggestions on improving it (it is a physical process, run by a
> microcontroller).
>
> I am struggling with how to document the code in a way that is
> helpful to us all. I did find some code beautifiers to make reading a
> bit less painful.
>
> For the docs, I've started by making a flowchart that walks through
> the logic and identifies which files subroutines can be found in. Is
> this what I should be doing? Am I doing way too much work? Is there
> some really awesome perl tool that maps out a function/tree structure
> for me? Is there some other way to do this?

You might want to try Sparse.  Not a Perl tool, but it can generate 
structure graphs among other things.

http://www.kernel.org/pub/software/devel/sparse/

-- 
"ANSI C says access to the padding fields of a struct is undefined.
ANSI C also says that struct assignment is a memcpy. Therefore struct
assignment in ANSI C is a violation of ANSI C..."
                                   - Alan Cox