hackersguide

早期freebsd实现

Hacking Notes from the hand of Larry Wall with respect to rn, trn's ancestor,
modified by Wayne Davison to reflect the current state of trn.

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

In the interests of both space and time optimization, things are done inside
trn 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 trn right from the
start.  In particular, if you want to hack on trn (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 information
    required to backup pages is not stored in memory, except for 1 buffer's
    worth.

  * 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.  Trn 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 trn as a big state machine.  If they don't bother
    you at all, I don't want you hacking on trn.

  * 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 trn.  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 trn 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 trn 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 trn 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.4.[2-9].  (I will use 4.4.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.