I am currently working on adding a fair amount of functionality to a Web site whose programs have been designed very poorly. Amongst other things, taint checking and strict have not been used. Code has been thrown together without regard to side effects, massive Here docs are used to output HTML, etc. Since I am getting a fair amount of experience with these issues, I thought I would offer some of my observations for fellow monks. Some of these pertain to the existing code and concentrates on 'quick fixes'. Some pertains to new code that's added.

Quick (?) Fixes

Adding new functionality

Any and all tips that others wish to add are welcome!

Cheers,
Ovid

Join the Perlmonks Setiathome Group or just click on the the link and check out our stats.

Replies are listed 'Best First'.
Re: Suggestions for working with poor code
by dws (Chancellor) on May 10, 2001 at 01:51 UTC
    Bad formatting can hide a number of sins.

    If necessary, the first thing I do when taking on bad code is reformat it. It doesn't matter whether it's Perl, Java, C, or HTML. A surprising number of problems (like mangled boolean conditions in branches and loops) fall right out when the code is tidied up so that you can actually see what it's doing.

    Then it's a lot easier to get on with the fixes Ovid suggests.

Re: Suggestions for working with poor code
by tinman (Curate) on May 10, 2001 at 02:02 UTC

    I've found that taking a deep breath and a step back from the turmoil of badly written code can help immensely.. quite a few instances where you can see places where code can be consolidated into a single reusable library..

    With this in mind, trying to understand the basic intent of the code is really important to me.. I write down a small note describing what each section of code tries to do... this allows me to focus on reuse as well as consolidate several segments together..

    Related to this: in addition to liberal comments, updating documentation or in some cases, writing some document that describes the structure and function of a code block is very helpful to any person maintaining the code.. you don't have to wonder "what was that guy thinking" or "why did he do *that* ?".. its all there in a document.. and also provides a cursory overview of what has been going on without jumping straight into the code (I'm a big fan of the saying that goes "the less time you spend planning, the more time you spend coding")...
    Caveat: Docs that aren't updated are worse than useless, though...

Re: Suggestions for working with poor code
by clemburg (Curate) on May 10, 2001 at 12:20 UTC

    Track how long it takes you to fix bugs.

    I agree enthusiastically. It will be your only argument when somebody comes and asks you where all the hours have gone. For this kind of job (take responsibility for badly written code, fixing bugs, etc.) this is an absolute must.

    For these purposes, two little forms (or spreadsheets, or editor modes/templates, or whatever) will be very helpful (pedantically detailed discussion of these can be found in An Introduction to the Personal Software Process, electronic materials are available at The PSP Resource Page, including time tracking tools, emacs modes, forms, etc.):

    • Time recording log
    • Defect recording log

    These are the essentials of both (header columns, add date, person, project, client, etc. as you need):

    Time recording log:

    • Start Time
    • Stop Time
    • Interruption Time
    • Delta Time
    • Activity Category (coding, testing, reading docs - make up your own)
    • Comments (more detailed description of task)

    Defect recording log:

    • Defect ID (e.g., sequential number)
    • Type (one of: documentation, syntax, build/package, assignment, interface, checking, data, function, system, environment - your own are welcome)
    • Inject Phase (when was the defect put into the program - estimate - design, coding, testing, linking, etc.)
    • Remove Phase (when was the defect found - compile time, testing, etc.)
    • Fix Time (how long did it take to fix)
    • Description (description of defect)

    Contrary to what you may think, it does *not* take much time to use these forms (or similar means to record the information). But it will give you all the data you need to be sure you did the Right Thing, and the confidence and evidence to convince your boss or client that what you did was worth the time and the money.

    Christian Lemburg
    Brainbench MVP for Perl
    http://www.brainbench.com

      You mean these logs haven't been automated into CPAN module yet??

      coreolyn Still looking for time to record time usage

Re: Suggestions for working with poor code
by r.joseph (Hermit) on May 10, 2001 at 04:04 UTC
    Wonderful post Ovid - just added to my favs list. For someone who had the great misfortune a while back of inheriting a large, ill-maintained and astrociously coded website, I know what you mean and this post really highlights some of the main points that go into fixing it.

    I also have to agree heartily with the replies, although I would like to add something. I find sometimes that it actually helps, with particularily insubordinate code, to take part of it out of the main file (say, a sub) and put it into another script that has major error-checking, lots of warnings and what not, and then test it from there. Sometimes this will yield a solution very quickly, and other times it has quickly allowed me to see what was wrong and what needed to be recoded.

    Just thought I'd offer a quick idea...great job again!

    r. j o s e p h
    "Violence is a last resort of the incompetent" - Salvor Hardin, Foundation by Issac AsimovW
Re: Suggestions for working with poor code
by knobunc (Pilgrim) on May 10, 2001 at 18:19 UTC

    Very cool node.

    With regard to the To Do list, I scatter them throughout my code if there is a place I need to do further work. However, I have a make rule for todo that searches for all of the lines with TODO in them and prints them out. So a usage of a TODO:

    if ($whatever) { # TODO - Finish code to take over the world }

    Becomes:

    To Do List Dir/file.pl 132: Finish code to take over the world

    When run through the following (ugly, suboptimal, but working) code in Tools/todo.sh:

    #/bin/sh echo 'To Do List' find . -type f | xargs grep -n TODO | perl -ne '($file, $line, $rest) += split /:/, $_, 3; $file =~ s|^./||; $rest =~ s|.*?TODO.*?[-\s:]+||; + $rest =~ s|"[.;,]\s*$||; $rest =~ s|\\n||g; print "$file $line: \u$r +est\n"' | sort | uniq | grep -v '.#' | grep -v Makefile | grep -v CVS +/

    Which I call from my Makefile:

    todo: Tools/todo.sh

    Kinda ugly, but it lets me put the TODO statements where I actually need to do the work. So I can proof out a block of code by writing narrative comments with TODO at the start of the line (behind comment characters of course). Then fill in the code later and not worry about missing a piece. Also since the TODOs are where the stuff needs to be filled in, I have lots of context around the issue and don't need to write as much as I would if they were at the top of the file. Plus anyone without something to do in the group can just type make todo and add some code. Finally, it is easier to add a TODO right where you need it, than bop up to the top of the file and then have to find where you were back in the code.

    -ben