Return to HACKERSGUIDE CVS log

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

Annotation of 43BSD/contrib/rn/HACKERSGUIDE, revision 1.1.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.