Learning Code...Fast

Jim Stewart <jstewart@jkmicro.com> wrote in message news:<ke6dnRJsMeT_KlXdRVn-sw@omsoft.com>...
> >Daniel McCarty wrote:
> >
> > (If the
> > dice of history rolled a little differently we might have all been
> > using Zinc instead of Java, but that's a topic for a different day.)
> 
> What gives you the idea we're all using Java?

   I just meant that those who do use Java might be using Zinc
instead.  But I'll save it for alt.history.what-if.

On 11 Jun 2004 07:08:05 -0700, Daniel McCarty <mcdan@csi.com> wrote:

>    I just meant that those who do use Java might be using Zinc
> instead.  But I'll save it for alt.history.what-if.

I saw Zinc library in early '90.  It was a rather impressive library of 
primitives for creating user interfaces under DOS (C compiler was not 
included).  How could that library be possibly used as a programming 
language eludes me.

  Vadim

Kelly Hall <khall@acm.org> wrote in message news:<e93yc.83149$wH5.73023@newssvr25.news.prodigy.com>...
> 
> I've worked in several places where we were exceptionally picky about 
> keeping the application logic and user interface and hardware calls 
> totally separate.  If you can afford the price, It's a good thing.

   By price I assume you mean the overhead of writing/maintaining more
code _and_ the performance overhead?  From what I understand the main
loop runs at ~50microsecs.  Assuming that abstracting the hardware out
of the main body of code won't be too much of a performance hit,
thanks very much for the tip.

Hans-Bernhard Broeker <broeker@physik.rwth-aachen.de> wrote in message news:<2itfbuFqpsmdU4@uni-berlin.de>...
> Daniel McCarty <mcdan@csi.com> wrote:
> 
> > 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.  
> 
> "so there" implies the latter is a direct consequence of the former.
> Mildly speaking, that's not exactly correct.  Just because it's an
> embedded system doesn't mean the code must be crap.

   I didn't mean that one implies the other.  I happen to have seen the code!  ;-)

mcdan@csi.com (Daniel McCarty) wrote:

>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. The pay raise would be nice, but the new job would require
>that I be able to bring a new project to market in as little time as
>possible.
>
>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.  As for
>the project being in Zinc, it's a pretty readable format.  (If the
>dice of history rolled a little differently we might have all been
>using Zinc instead of Java, but that's a topic for a different day.)
>
>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?

Absolutely, positively, and beyond a shadow of a doubt, the most
valuable tool I have used in these types of situations is "Understand
for C/C++" by Scientific Toolworks, Inc.

http://www.scitools.com/ucpp.html

I was introduced to it a few months ago on a 500K-line C program as a
contractor/consultant and found it *so invaluable* that I (how's that
electric shaver commercial go?) bought the product for my own
toolchest for those other clients that dump their code on me and ask
"how long will it take you to ________?".  Now I have a tool that give
me much more confidence in my Rough Order of Magnitude estimates for
performing modifications without breaking something else.

[I'm only a happy customer, nothing more.]

--
Dan Henry

On Sat, 12 Jun 2004 09:29:46 -0600, Dan Henry <dhenry@sprynet.com>
wrote:

>mcdan@csi.com (Daniel McCarty) wrote:
>
>>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. The pay raise would be nice, but the new job would require
>>that I be able to bring a new project to market in as little time as
>>possible.
>>
>>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.  As for
>>the project being in Zinc, it's a pretty readable format.  (If the
>>dice of history rolled a little differently we might have all been
>>using Zinc instead of Java, but that's a topic for a different day.)
>>
>>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?
>
>Absolutely, positively, and beyond a shadow of a doubt, the most
>valuable tool I have used in these types of situations is "Understand
>for C/C++" by Scientific Toolworks, Inc.
>
>http://www.scitools.com/ucpp.html
>
>I was introduced to it a few months ago on a 500K-line C program as a
>contractor/consultant and found it *so invaluable* that I (how's that
>electric shaver commercial go?) bought the product for my own
>toolchest for those other clients that dump their code on me and ask
>"how long will it take you to ________?".  Now I have a tool that give
>me much more confidence in my Rough Order of Magnitude estimates for
>performing modifications without breaking something else.
>
>[I'm only a happy customer, nothing more.]

I have used this tool as well, and can also recommend it. It is also
great for generating piles of documentation to keep certain types of 
QA people happy. (Here in South Africa there is a tendancy to use
people who are useless at anything else for QA)
It of course can also be used to generate very usefull documentation
as well - hyperlinked to the actual source etc.

Regards
   Anton Erasmus

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

Ed Beroset <beroset@mindspring.com> wrote:

[...]
> Using a static const (equivalent of C style #define, but with 
> typechecking) 
[...]

I sure would be nice if it were, but it's not.  Variables flagged
'const' don't qualify as constants in at least some of the more
important usages.  Most importantly, they can't be used to define an
array size (unless it's a C99-ish variable-size array).  It's
therefore actually preferrable to stick to #define, or, if the magic
cookie in question is an integer, use an enum.

-- 
Hans-Bernhard Broeker (broeker@physik.rwth-aachen.de)
Even if all the snow were burnt, ashes would remain.

Hans-Bernhard Broeker wrote:
> Ed Beroset <beroset@mindspring.com> wrote:
> 
> [...]
> 
>>Using a static const (equivalent of C style #define, but with 
>>typechecking) 
> 
> [...]
> 
> It sure would be nice if it were, but it's not.  Variables flagged
> 'const' don't qualify as constants in at least some of the more
> important usages.  Most importantly, they can't be used to define an
> array size (unless it's a C99-ish variable-size array).  

I think you missed the context which was a *C++* program, not C.  In 
C++, not only can one use a const this way, but it is explicitly called 
out as good practice.  See _The C++ Programming Language, Third 
Edition_, by Bjarne Stroustrup, p. 96.  It's one of the many reasons I 
prefer C++ to C.

Ed

Ed Beroset <beroset@mindspring.com> wrote:

> I think you missed the context which was a *C++* program, not C.  

Yep, you're right.  Sorry about any confusion I may have caused.


-- 
Hans-Bernhard Broeker (broeker@physik.rwth-aachen.de)
Even if all the snow were burnt, ashes would remain.