Return to HACKERSGUIDE CVS log

Up to [CSRG BSD Unix] / 43BSD / contrib / rn

Annotation of 43BSD/contrib/rn/HACKERSGUIDE, revision 1.1

1.1     ! root        1: Hacking Notes
        !             2: 
        !             3: If you aren't interested in mucking with the innards of rn, don't read this.
        !             4: 
        !             5: In the interests of both space and time optimization, things are done inside
        !             6: rn that don't always conform to the highest ideals of programming.  To the
        !             7: extent I felt it was practical, I've tried to conform to good programming
        !             8: practice, but you must realize that my goal was to make a better mousetrap,
        !             9: so certain conscious tradeoffs were made in the design of rn right from the
        !            10: start.  In particular, if you want to hack on rn (and I wouldn't blame you,
        !            11: it's fun), beware of the following:
        !            12:   
        !            13:   * buf and cmd_buf are reused all over the place.  11-squishing is a good
        !            14:     term for it.  No, I'm on a Vax now, but I've been there.
        !            15: 
        !            16:   * The article header is parsed on the fly, while it is being displayed.
        !            17:     In fact, practically everything is done on the fly within the article
        !            18:     display loop, and there are plenty of state variables.  The header
        !            19:     is never explicitly stored in memory; rather, pointers are kept into
        !            20:     the file.  The information required to backup pages is not stored in
        !            21:     memory, except for 1 buffer's worth.  The information required to do
        !            22:     the delayed mark as unread (M) is not stored in memory either.
        !            23: 
        !            24:   * Lots of contortions are gone through to avoid using static memory, or
        !            25:     allocating unnecessary memory, or losing track of allocated memory,
        !            26:     while at the same time allowing .newsrc lines and header lines to be
        !            27:     ANY length up to the amount of memory you have.  Rn spends a great deal
        !            28:     of effort being lazy.  Do not use a static buffer when you can use
        !            29:     growstr().
        !            30: 
        !            31:   * Lots of contortions are gone through to try to do things when people
        !            32:     aren't waiting, or have only been waiting a very short time.  Guessing
        !            33:     the next article to be opened and opening it, searching ahead for the
        !            34:     next article with the same subject, delaying the look up of the number
        !            35:     of articles in a newsgroup, writing the rest of the page while the
        !            36:     reader is examining the header, cacheing up subjects while the user
        !            37:     is reading, checkpointing the .newsrc only while the reader is in the
        !            38:     middle of an interesting article, are some of the strategies employed.
        !            39:   
        !            40:   * There are plenty of goto's.  Most of them involve going back to reprompt,
        !            41:     to reask for input, or to just plain do the unstructured things people
        !            42:     want to do when they are glaring at a terminal.  If they bother you
        !            43:     too much, just think of rn as a big state machine.  If they don't bother
        !            44:     you at all, I don't want you hacking on rn.
        !            45: 
        !            46:   * Put all includes at the front of the file, before the first function,
        !            47:     or makedepend will not work right.  I could relax this, but makedepend
        !            48:     would take about 5 times longer to run.
        !            49: 
        !            50: In general then, feel free to hack on rn.  Just don't broadcast untested
        !            51: patches to the net.  Remember that there are people with limited address
        !            52: spaces and limited cpu cycles.  If you add a wonderful new feature and
        !            53: want to publish a patch, put #ifdef's around it so that people who don't
        !            54: want it or can't afford it can work around it.  THIS MEANS YOU.  We don't
        !            55: need 57 varieties of mutually incompatible and incomprehensible rn floating
        !            56: about the net.  Consider telling me about your patch so that I can consider
        !            57: including it in the standard version.  A COMPLETE PATCH TAKES INTO ACCOUNT
        !            58: SYSTEM DEPENDENCIES AS DETERMINED BY THE CONFIGURE SCRIPT.
        !            59: 
        !            60: * Don't use ints where rn uses typedefs, in particular, for article numbers.
        !            61: * Don't use %d anywhere that someone might need a %ld.  (Just because YOU
        !            62:     typedefed it as an int doesn't mean someone else won't need a long.)
        !            63: * Don't use %D, that's archaic.
        !            64: * Put FLUSHes after printf()s, fputs()es and putchar('\n')s for our poor
        !            65:     brethern and sistern without line buffering.
        !            66: * Declare the type of every function.  Use void, even if your C compiler
        !            67:     doesn't.
        !            68: * Follow the style that rn already uses!  This is my pet peeve.  Well, one of
        !            69:     them, anyway.  I follow other people's strange styles when modifying
        !            70:     their programs, so I'd be much obliged if you did likewise.
        !            71: * Use lint.
        !            72: * Use RCS.  Start a new branch, like 4.3.[2-9].  (I will use 4.3.1 myself.)
        !            73: * Be structured wherever it doesn't interfere with practicality.
        !            74: * Long live paranoid programming.  The rest of the program is out to get you.
        !            75:     The world is out to destroy the program, not to mention the .newsrc.
        !            76:     And then there's always bitrot...
        !            77: * Stop reading this lugubrious trash and start thinking for yourself.
        !            78: * Thank you and good night.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.