4.3BSD/usr/contrib/rn/HACKERSGUIDE

Hacking Notes

If you aren't interested in mucking with the innards of rn, don't read this.

In the interests of both space and time optimization, things are done inside
rn that don't always conform to the highest ideals of programming.  To the
extent I felt it was practical, I've tried to conform to good programming
practice, but you must realize that my goal was to make a better mousetrap,
so certain conscious tradeoffs were made in the design of rn right from the
start.  In particular, if you want to hack on rn (and I wouldn't blame you,
it's fun), beware of the following:
  
  * buf and cmd_buf are reused all over the place.  11-squishing is a good
    term for it.  No, I'm on a Vax now, but I've been there.

  * The article header is parsed on the fly, while it is being displayed.
    In fact, practically everything is done on the fly within the article
    display loop, and there are plenty of state variables.  The header
    is never explicitly stored in memory; rather, pointers are kept into
    the file.  The information required to backup pages is not stored in
    memory, except for 1 buffer's worth.  The information required to do
    the delayed mark as unread (M) is not stored in memory either.

  * Lots of contortions are gone through to avoid using static memory, or
    allocating unnecessary memory, or losing track of allocated memory,
    while at the same time allowing .newsrc lines and header lines to be
    ANY length up to the amount of memory you have.  Rn spends a great deal
    of effort being lazy.  Do not use a static buffer when you can use
    growstr().

  * Lots of contortions are gone through to try to do things when people
    aren't waiting, or have only been waiting a very short time.  Guessing
    the next article to be opened and opening it, searching ahead for the
    next article with the same subject, delaying the look up of the number
    of articles in a newsgroup, writing the rest of the page while the
    reader is examining the header, cacheing up subjects while the user
    is reading, checkpointing the .newsrc only while the reader is in the
    middle of an interesting article, are some of the strategies employed.
  
  * There are plenty of goto's.  Most of them involve going back to reprompt,
    to reask for input, or to just plain do the unstructured things people
    want to do when they are glaring at a terminal.  If they bother you
    too much, just think of rn as a big state machine.  If they don't bother
    you at all, I don't want you hacking on rn.

  * Put all includes at the front of the file, before the first function,
    or makedepend will not work right.  I could relax this, but makedepend
    would take about 5 times longer to run.

In general then, feel free to hack on rn.  Just don't broadcast untested
patches to the net.  Remember that there are people with limited address
spaces and limited cpu cycles.  If you add a wonderful new feature and
want to publish a patch, put #ifdef's around it so that people who don't
want it or can't afford it can work around it.  THIS MEANS YOU.  We don't
need 57 varieties of mutually incompatible and incomprehensible rn floating
about the net.  Consider telling me about your patch so that I can consider
including it in the standard version.  A COMPLETE PATCH TAKES INTO ACCOUNT
SYSTEM DEPENDENCIES AS DETERMINED BY THE CONFIGURE SCRIPT.

* Don't use ints where rn uses typedefs, in particular, for article numbers.
* Don't use %d anywhere that someone might need a %ld.  (Just because YOU
    typedefed it as an int doesn't mean someone else won't need a long.)
* Don't use %D, that's archaic.
* Put FLUSHes after printf()s, fputs()es and putchar('\n')s for our poor
    brethern and sistern without line buffering.
* Declare the type of every function.  Use void, even if your C compiler
    doesn't.
* Follow the style that rn already uses!  This is my pet peeve.  Well, one of
    them, anyway.  I follow other people's strange styles when modifying
    their programs, so I'd be much obliged if you did likewise.
* Use lint.
* Use RCS.  Start a new branch, like 4.3.[2-9].  (I will use 4.3.1 myself.)
* Be structured wherever it doesn't interfere with practicality.
* Long live paranoid programming.  The rest of the program is out to get you.
    The world is out to destroy the program, not to mention the .newsrc.
    And then there's always bitrot...
* Stop reading this lugubrious trash and start thinking for yourself.
* Thank you and good night.