home *** CD-ROM | disk | FTP | other *** search
/ Usenet 1994 January / usenetsourcesnewsgroupsinfomagicjanuary1994.iso / sources / unix / volume25 / trn / part02 / HACKERSGUIDE < prev    next >
Encoding:
Text File  |  1991-12-02  |  4.4 KB  |  79 lines
  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.4.[2-9].  (I will use 4.4.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.
  79.