Re: Learning Code...Fast

From: Ed Beroset (beroset_at_mindspring.com)
Date: 06/13/04 

Date: Sun, 13 Jun 2004 15:51:34 GMT

Daniel McCarty wrote:
> (At the recommendation of a colleague I'm posting this here as well,
> after posting to comp.programming.)
>
> I've been given an opportunity to start on a 100,000 line, C++
> software project that uses a nearly obsolete toolkit
> (http://www.openatc.org/zinc/) and is, shall we say, "leanly"
> documented.

IMHO, this is often an indication of poor quality.

> I should mention that it's an embedded systems project, so there are a
> lot of magic numbers, memory addresses and hardware intricacies
> sprinkled throughout the code. That may be the toughest part.

Just because it's an embedded system doesn't mean the code needs to be
lousy. Using a static const (equivalent of C style #define, but with
typechecking) adds NO additional runtime space or time requirement, so
having "magic numbers" is simply inexcusable. This is a really big red
flag for me.

> The first thing that I may have to do would be to write the project
> documentation, if only for my own sanity. But other than staring at
> code from morning till night day after day, are there any other tips
> and tricks that experienced programmers have found to help get them up
> to speed on a project quickly?

Yes. First, you already know the bad news -- the code quality is
suspect, and I'm sure this means that the requirements are nonexistent
and the testing was cursory at best. You're likely to improve the code
at some point, only to discover that somebody or something was relying
on some "undocumented feature" (a.k.a. bug) that can't be eliminated for
economic reasons. Beware of duplicating this mistake when you clean
things up.

But with all of that aside, I have to tell you that when I've done work
like this, I've enjoyed it. I like fixing things! :-) Here are some
tools and techniques I'd recommend:

Doxygen -- a GPL tool for documenting C++ code. This thing is great,
and the price is right! If you've used javadoc, you already have some
idea about how this works. Get it at http://www.doxygen.org

Rational -- this is a cranky tool, IMHO, and rather pricey for what used
to be a pretty poor quality tool, but maybe IBM has fixed things up
since they acquired it. (I haven't used it for some years.) Look up
"Rational" and "round trip engineering" on Google to find it. Last time
I used it, you could point it at a directory tree full of code and it
would create class diagrams for everything. This by itself isn't that
helpful, perhaps, but you can then create things like sequence diagrams
using the correct class names without a lot of effort. (Well, there's
still the effort of analyzing the code, but at least the drawings are
easier with a tool.)

If you want to have a hope of turning this into decent quality software,
   you're going to need more than just documentation. I'd recommend
doing automated unit testing using something like CppUnit (see
http://cppunit.sourceforge.net/cgi-bin/moin.cgi/FrontPage ) which can
also be used to test your understanding of what the current code is
*supposed* to do.

Source code control is a necessity. CVS is free and ubiquitous. What
you choose is less important than using *something.*

When you're setting up the repository, don't forget to check in or at
least document the required build tools, too. Step 0 should be to
verify that you can actually build the code and get an *identical*
binary (or binaries) to the current original. I'd highly recommend make
and not some proprietary build tool. Make skills are portable to other
projects, proprietary tool skills are often not. This also helps when
doing the first pass of code cleanup. You can start exclusively with
things which do NOT make changes to the resulting binary (e.g. replacing
all of those hideous magic numbers, commenting, reformatting). You can
then easily verify your results without testing by simply comparing the
binaries.

Finally, don't underestimate the power and utility of a really great
code editor. Choose one and become *expert* at using it -- the time you
spend on that task will pay off many times over if you choose a decent
editor to begin with. Rather than touch off a flamewar, I'll leave it
to you to decide what qualities would be required for a decent code editor.

Hope that helps. Good luck and have fun!

Ed

Relevant Pages

  • Re: Suggestions for compact camcorder for new daddy
    ... I can't recommend a specific model. ... I use a Sony VX2000, ... >around $275 for its consumer camcorders. ... >> I am looking to buy a good quality digital camcorder. ...
    (rec.video)
  • Re: Moving from snapshots to photographs
    ... images are seeking is better processing/finishing of their images. ... I strongly recommend you persevere in trying to master these skills in the ... If you want high quality prints you should forget Walmart et al and learn to ... This also requires basic understanding of color management ...
    (rec.photo.digital)
  • Re: Bit-rate
    ... I've not done any A:B comparisons but I'm happy with the quality. ... Apple Lossless for the encoding from that, to be done when importing to ... settings to, though; my instinct is to set it to max, i.e. 96000Hz. ... I'd recommend making a couple of sample recordings and transcodings to compressed and listening through carefully before committing to recording the lot, I've had problems in the past with occasional clicks, pops and mutes on some combinations of settings, that I hadn't noticed at the time and had to go back and re-record. ...
    (uk.misc)
  • Re: Home Network, step by step?
    ... I would also recommend going with pf. ... documentation is fantastic, it can do a myriad of things and is ... > ipf and pf in FreeBSD - are now not so much firewalls, ... IPFW is much older and is somewhat less well maintained, ...
    (freebsd-newbies)
  • Re: A better find subroutine
    ... to do this and frankly thats why i'm posting in perl begginers:) ... I recommend just reading that module's documentation. ... For CPAN modules, ...
    (perl.beginners)