[MUD-Dev] TECH: Managing all your code

[J C Lawrence]

On Tue, 8 Jan 2002 14:41:55 -0500 (EST) 
Eric Rhea <eric at enkanica.com> wrote:

> I'm starting to feel the strain of managing a large number of
> projects, written in various languages and with each differing in
> size, length, and purpose. I think the management aspect of this
> would be a fairly common problem - if not, then what are you doing
> to keep it all under control? Is there some common app that most
> use to handle what source you have, the purpose of that snippet,
> licensing for that particular piece, etc?

There are several problems masquerading as one.

  1) The problem of keeping track of the many little bits and pieces.

  2) The problem of keeping track of what all the little bits and
  pieces mean, and what value they have.

  3) The problem of keeping track of how all the little bits and
  pieces change over time and how that changes their meaning

  4) The problem of keeping track of how all the little bits and
  pieces change over time and how that affects their value and
  integration with all the other little bits and pieces.

  5) The problem of finding the little bit that does or can do what
  you are interested in or looking for.

  6) The problem of determining and realising how all the little
  bits and pieces plug together and form an architecture.

  7) The problem of understanding what problems each of the little
  bits and pieces solves, AND what problems they also create in
  rendering that solution.

  8) etc (and there are quite a few etceteras to this list).

They're not simple problems.

Most interestingly they all sum to, "Understanding what is going on
and what it means".  The problem is that description is too general
to be much use.  So, in classical engineering fashion, you
sub-divide the problem and then try and solve the smaller bits to
see if you can't get a solution to the bigger problem that way.

Some common tools and subdivisions:

  Use a source change management tool (SCM).  ie a system to keep
  track of all your sources, how they change, who changed them,
  when, why, how, etc.  There are scores of products in this arena.
  They all have variously different strengths and weaknesses.  They
  all create additional problems of various calibres.  Common
  examples enclude CVS, SCCS, RCS, VCS, ClearCase, Perforce, ptools,
  VSS, BitKeeper and many many others.

  ObAdvocacy: I particularly dislike CVS (see prior rants) and
  like/use/advocate BitKeeper (http://www.bitkeeper.com/) in
  general for this area.

    An SCM tool can help with #1, parts of #3, and parts of #4.

  Source documenting systems range from things like JavaDoc (and its
  many variants for other languages) all they way down to Knuth's
  literate programming (http://www.literateprogramming.com/)
  efforts.  There's been a lot of effort in this area over a very
  long time.  The number of tools and attempted solutions in the
  space is bewilderingly large.

  ObAdvocacy: I like (and mostly don't use out of incorrigible
  laziness) JavaDoc (and its variants).  JavaDoc does good things in
  a fairly pain free manner (well, more pain free than most others).

    Source documentation systems can help with #2, #5, and bits of
    #6.

  Tracking systems have a similarly wide range of implementations,
  models etc.  I've never seen one I really liked (tho SGI's in
  house system came close) so I won't comment on details here.  Such
  systems are generally known as ticketing systems, bug tracking
  systems, or defect tracking systems (there is a subtle
  definitional difference between the three).

    Tracking systems can help with parts of #3, bits of #4, and some
    of #7.

  Documentation systems help define, dictate, and communicate
  architectures and understanding of systems.  This plugs into and
  is part of another whole field (which is quite enormous) called,
  "Knowledge Management".  The range of tools available here is
  massive.

  ObAdvocacy: I tend to like very simple easily edited tools for
  these aspects, and generally advocate WikiWikis, and in particular
  TWiki for the general case.  Nice tool.

    Documentation systems can help with bits of #1, most of #2,
    parts of #3, parts of #4, small bits of #5, #6, and parts of #7.

  Source browsers can help gain overviews of source sets, and, if
  integrated with SCM systems, how a source base evolves over time
  (note that they are different but related problems).  This tends
  to be a religious area with individuals having strong preferences
  and feelings about what works for them.

  ObAdvocacy: I'm rapturously in love with BitKeeper's "promerge"
  tool for watching source base evolution.  I also use XEMacs'
  oobrowser, exuberant etags, cscope, and other tools frequently for
  analysis of a static source base/architecture.

  Note: There was a minor thread on this area on the meta at kanga.nu
  list recently.  You might want to check the archives.

    Source browsers can help with #2, #3, parts of #4, #5, and bits
    of #7.

Summary:

  There are no perfect all encompassing solutions.  Its rather
  unlikely that there ever will be as the basic problem that's being
  solved is making sure that some human fully understands the
  design, architecture, construction, operation, implications, and
  history of a (set of) variously large and complex systems.

  That's a pretty personal thing, human understanding.  You can help
  it, but you can never guarantee it.

ObCommentary:

  That's why they pay architects the big bucks.

--
J C Lawrence                
---------(*)                Satan, oscillate my metallic sonatas. 
claw at kanga.nu               He lived as a devil, eh?		  
http://www.kanga.nu/~claw/  Evil is a name of a foeman, as I live.
_______________________________________________
MUD-Dev mailing list
MUD-Dev at kanga.nu
https://www.kanga.nu/lists/listinfo/mud-dev