The best way to learn a legacy code base....

...is by writing some tests for it :)

Hey there fellow dinosaurs,

One problem with hacking on trn is that it has absolutely no automated
tests for it, so you have to resort to lots of time in the debugger.
Reading the source code isn't much help either as what comments are
present don't reveal much of the design intent, but more local details
of whatever is happening at the location of the comment.  There is
also the usual input impedence related to reading someone else's code:
formatting and naming conventions deviate from your own personal
tastes, etc.

One thing trn does have going for it is the ability to tweak things to
the nth degree through external files and environment variables.

That gives us a hook into testing chunks of the code.

I used CMake's configure_file() function to create a bunch of related
text files in the build directory that act as test inputs to trn.
Using code generated from the same CMake variables I was able to set
the relevant environment variables to point at my generated files
during running of the tests.

I've now gotten to where I've got trn parsing generated news articles
in the "local news spool" (directories and files generated by CMake).
I wrote tests for every special % interpolation and now a bunch of the
ones related to article headers are passing and at least none of them
are crashing anymore :-).  Every time I work on getting one more fancy
% interpolation construct passing, I learn a little more about the
code.  This paves the way for making future changes in a safe manner.

Because some of the changes I've got in mind are pretty substantial in
terms of architecture, it's important to have a safety backstop to
catch mistakes.

This also brings up the age-old question in software: "refactor or
rewrite?".  My general long-standing opinion on this (based on some
good and bad experiences over many years) is always "refactor" with a
smidge of "rewrite".  By this I mean, trn has lots of the features I
want in a news reader, but lacks some of the features I'd like in a
news reader.  Rather than write my own news reader completely from
scratch, it's cheaper to refactor my changes into trn.  Considering
that trn has shifted maintainers several points in its lifetime given
its heritage, it's clear that the previous maintainers also though
that it was better to "refactor" their new features into existing code
than to start from scratch.

Along the way I've tried not to make sweeping code changes across all
the files.  TABs are still not expanded in source files :-).  Some
global changes happened in order to aid me in understanding the code.
File scope static variables were renamed to have 's_' prefix and
global scope variables were renamed to have 'g_' prefix in order to
more readily recognize connections to distant data when reading a
function.

I recently hit upon a design approach for the asynchronous NNTP engine
I'd like to drop into trn and I'll be prototyping this separately with
boost.asio for my Utah C++ Programmers talk next week.  I think that's
going to work out nicely and result in an asynchronous NNTP command
processor that can handle pipelining of commands as documented in the
NNTP RFC.  Reading over the RFCs relating to NNTP it's clear that some
of the "standard" features in the current NNTP spec were created after
the last time trn had any significant kind of release.

I looked over the tickets in the trn sourceforge repository and
created a couple issues in my github fork to incorporate some
fixes/changes that don't appear to have yet been integrated into the
trn source.

Cheers,

-- Richard

-- 
"The Direct3D Graphics Pipeline" free book <http://tinyurl.com/d3d-pipeline>
             The Terminals Wiki <http://terminals-wiki.org>
     The Computer Graphics Museum <http://ComputerGraphicsMuseum.org>
  Legalize Adulthood! (my blog) <http://LegalizeAdulthood.wordpress.com>