pd.if.org Git - pdclib.old/blob - Notes.txt

   1 Credits
   2 =======
   3
   4 The vast majority of PDCLib is original work by me. I felt it was the only way
   5 to ensure that the code was indeed free of third-party rights, and thus free to
   6 be released into the Public Domain.
   7
   8 Another issue was that of coding style, quality and stability of the code, and
   9 the urge to really understand every miniscule part of the code as to be able to
  10 maintain it well once v1.0 has been released.
  11
  12 That is not to say there are no credits to be given. To the contrary:
  13
  14 Paul Edwards (author of the PDPCLIB), for inspirational code fragments, thanks.
  15
  16 P.J. Plauger (author of "The Standard C Library"), for a book without which I
  17 would not have been able to create PDCLib at this quality, thanks.
  18
  19 Paul Bourke (author of mathlib), for allowing me access to a complete math
  20 library under public domain terms so I could use it as a reference, thanks.
  21
  22 Peter ("Candy") Bindels (netizen of mega-tokyo.com), who located a copy of Cody
  23 & Waite's "Software Manual for the Elementary Functions" for me and saved me
  24 serious cash in the process, thanks.
  25
  26 Michael Moody, who contributed the generic implementation for <stdarg.h> which
  27 can now be found in <_PDCLIB_config.h> to the Public Domain, thanks.
  28
  29 Rod Pemberton, for pointing out several flaws in early versions of PDCLib and
  30 giving other valuable hints, thanks.
  31
  32 Everyone involved in the first, "public" attempt at PDCLib, for bearing with me
  33 when I restarted from scratch, thanks.
  34
  35 Lennart Fridén and Sammy Nordström, who have been great pals even after I sunk
  36 another project that had eaten countless hours of work between the three of us,
  37 thanks.
  38
  39 My wife and daughter, for sharing husband and daddy with this strange machine,
  40 thanks.
  41
  42
  43 Style
  44 =====
  45
  46 I followed a set of guidelines in creating PDCLib. If you find some piece that
  47 does not adhere to them, that's a bug worth reporting. I mean it. I am a bit
  48 obsessive when it comes to coding style. ;-)
  49
  50 - all the stuff that is not part of the standard specification is "hidden" in
  51   the _PDCLIB_* namespace - functions, variables, macros, files, directories.
  52   This is to make it easier to distinguish between what the standard dictates
  53   and what I added to make PDCLib work.
  54
  55 - any internal includes (i.e. those not specified by the standard) have their
  56   header guards defined in the *including* file, for a tiny bit of performance.
  57
  58 - I always try to minimize the use of local variables. Wherever possible I used
  59   the parameters directly, and deferred declaration of locals to the innermost
  60   block of statements, in hopes that it might reduce memory footprint when the
  61   library is compiled with a compiler that is not that great at optimization.
  62
  63 - every function, every static data item that could possibly be shared, got its
  64   own implementation file. This means the library itself is probably larger than
  65   strictly necessary, and might take a couple of clock cycles longer to link,
  66   but it reduces size of fully-linked object files / executables.
  67
  68 - where possible, I tried to share functionality between similar functions (as
  69   can be seen in the atoi() and strtol() function families). This means one or
  70   two additional function calls, but again reduces memory footprint and eases
  71   maintenance of the library.
  72
  73 - standard function arguments are named exactly as in the standard document.
  74
  75 - the standard is taken quite literally in places. For example, memcpy() really
  76   copies char-wise. This runs contrary to earlier claims of performance, but is
  77   consistent with the *letter* of the standard, and you will probably use your
  78   compiler builtins (through a platform overlay) anyhow.
  79
  80 - every file (except the top-level *.txt files) has an Id and a Name tag, so
  81   that the CVS Id string is on file for *every* code file, and the release tag
  82   is on file for every code file in a release package.
  83
  84 - PDCLib code has no bias towards POSIX; indeed the absence of POSIX tidbits is
  85   one of its hallmarks. However, PDCLib also has no bias *against* POSIX, and
  86   when one platform abstraction is as good as another, I chose the POSIX one for
  87   sheer familiarity. (This is mainly referring to naming and parameter lists of
  88   OS "glue" functions.)
  89
  90 - identifiers are tersely named, but not cryptically abbreviated, and should be
  91   intuitive enough to allow easy understanding of PDCLib inner workings.
  92
  93 - I disagree with the notion that good code needs no comments. Code tells you
  94   *how*, but not the *why*, and you have to figure out the *what* yourself. So
  95   I added comments to every nontrivial piece of code explaining my motives and
  96   hopefully keeping overly ambitious editors from repeating my mistakes. The
  97   header files especially should be self-documenting to the point of being a
  98   suitable replacement for any library reference book you might be using.