in reply to Re^2: Analyzing large Perl code base.
in thread Analyzing large Perl code base.

You don't need to document the dreck you have. You need to document what marketing believes the dreck you have does. The last place you want to look for that is the actual source code.

Now, I only say this because the OP said (and I paraphrase) "I have a bunch of spaghetti that I can't figure out, so how do I clean it up?" The answer is "Write some tests, then refactor, then write some tests, then refactor, then ..."

Your testsuite then becomes the basis for your documentation. Obviously, you convert all the ok() calls into English or Swahili or whatever, but it's still the foundation.

My wife's blog

Replies are listed 'Best First'.
Re^4: Analyzing large Perl code base.
by kscaldef (Pilgrim) on Apr 15, 2005 at 16:40 UTC
    Well, that works until you go to the business and ask, "Where's the spec for feature X?" and they response, "Uh... well, what does it do now?".
[reply]
      That's perfect - you get to write your own specs! :-)
      • Developer: What's the spec for feature X?
      • Marketing: Uhhh ... well, what does it do now?
      • Developer: It should do foo, bar, and baz.
      • Marketing: Ok, sounds good to me.
      • Developer: Do you mind if I write that up and send it to you for a signature?
      • Marketing: (worried tone) Why would you do that?
      • Developer: Just so that if I screw up, you can hold my feet to the fire.
      • Marketing: (relieved tone) Oh, ok!

      So, you then write whatever you want, Marketing signs off on it, and you go write your test suite, refactor against it, and everyone goes home.

      My wife's blog

[reply]
        That may work okay for some places, particularly if your revenue stream is only loosely coupled to the code in question. Personally, the code I work on has a lot of revenue pushed through it every day, in a very quantitative manner. So, refactoring from what it does do to what it "should" do is fairly risky. What looks best to the developer isn't always best for the business, and even if a change is for the better any unexpected changes in the metrics raise flags.

        YMMV, but I think that in a organization of any significant size, it's generally a bad idea for developers to make unilateral decisions about how the product should be changed.

[reply]

In Section Seekers of Perl Wisdom