Path: utzoo!attcan!uunet!husc6!linus!philabs!ttidca!hollombe From: hollombe@ttidca.TTI.COM (The Polymath) Newsgroups: comp.software-eng Subject: Re: How will your code look to the hot-shots of 1993? Keywords: Software Maintenance Message-ID: <2960@ttidca.TTI.COM> Date: 25 Jul 88 22:37:19 GMT References: <12398@agate.BERKELEY.EDU> Reply-To: hollombe@ttidcb.tti.com (The Polymath) Organization: The Cat Factory Lines: 70 In article <12398@agate.BERKELEY.EDU> bks@ALFA.berkeley.edu (Brad Sherman) writes: }Everyone seems to have a plan for producing good software, but could we }have some discussion of how to go about fixing and modifying existing code? }I think that this task is more typical than most that have been discussed in }this group. How should a programmer go about internalizing enough of the }workings of the system to have a shot at succesful completion? Probably most of us have done more of this than almost anything else during our time in the D.P. biz. My last experience with it involved over 4,000 lines of C so crufty the original authors refused to touch it. Here's how I went about it: Step zero: Keep multi-generation backups. Be able to fall back to the original code, if necessary. (Sounds trite, I know, but I've seen self-styled "Real(tm) Programmers" happily go in and modify the only existing version of a major system's source code with no backups. I get the shakes just thinking about it). Step one: Reformat the code to something readable. Do it by hand, not with a pretty printer. In the two days I spent doing this I uncovered and fixed six major bugs that had been obscured by incorrect indentation and general cruft. The STR's on some of them were over 18 months old. Step two: Eliminate the unnecessary (but make _sure_ it's unnecessary). I wound up deleting over 1,000 lines of code that either did nothing or did nothing necessary. Much of it was debug left over from the original creation of the beast. Step three: Add comments. In particular, make sure every declared constant and variable has a comment description. Likewise for functions and subroutines. Exceptionally tricky or crufty code should be commented line by line, if necessary. This will give you a fair idea of what the program is doing and how it does it. (My personal commenting standard: All comments are delimited line by line. This makes accidentally including live code in a comment much less likely). Step four: This is a quick and dirty trick I occasionally have use for. If your system doesn't have a program trace capability, you can add a rough one by putting #ifdef TRACE printf ("PROGRAM_NAME: Function_name() \n"); fflush (stdout); #endif at the start of each function. The fflush() makes it more likely you'll get the last line out if something crashes. Step five: Document. If documentation doesn't exist, write it. If it exists, update it. If it's up to date, keep it that way. Step six: Now you're ready to start making changes. After you've designed them (you do design before you code, don't you?) try to implement and test as modularly possible. Debugging is much more of an adventure if you try to change everything at once. (Adventure: n., Someone else having a hard time, very far away). End result: What started out as a buggy and much distrusted system hasn't had a valid STR written against it in over a year. Its capabilities have been enhanced to do things the original authors thought were impossible or too complex to bother with (or never thought of at all). People are starting to realize the beast is maintainable, after all. I'm getting a lot of requests for more enhancements and upgrades. -- The Polymath (aka: Jerry Hollombe, hollombe@ttidca.tti.com) Illegitimati Nil Citicorp(+)TTI Carborundum 3100 Ocean Park Blvd. (213) 452-9191, x2483 Santa Monica, CA 90405 {csun|philabs|psivax}!ttidca!hollombe