home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 35 Internet / 35-Internet.zip / trn_197b.zip / HACKERSGUIDE < prev    next >
Text File  |  1993-02-23  |  4KB  |  78 lines

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