home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 4 / Apprentice-Release4.iso / Demos / OOFILE / docs / misc.txt < prev    next >
Encoding:
Text File  |  1995-07-13  |  12.1 KB  |  273 lines  |  [TEXT/ttxt]

  1. This is a kind of grab-bag of conventions, c++ concepts and a resource list.
  2.  
  3. -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  4.                ************ OOFILE CONVENTIONS *************
  5.  
  6.  NOTE ON IMPLEMENTATION TECHNIQUES
  7.  I have steered away from using templates and nested classes
  8.  despite there being a few places where normal c++ practice
  9.  would mandate their use. This is to avoid problems with
  10.  compilers that lack or poorly implement these features.
  11.  
  12.  
  13.  UNDER CONSTRUCTION
  14.  I've tried to finish the protocols of all the classes
  15.  and include skeleton methods. Look for the string
  16.  NOT YET IMPLEMENTED in comments.
  17.  
  18.  
  19.  CONVENTIONS
  20.  internal classes are prefixed by OOF_
  21.  
  22.  external classes are prefixed by db
  23.  
  24.  static members start with an 's' followed by an uppercase letter
  25.  
  26.  all other members start with an 'm' followed by an uppercase letter
  27.  
  28.  constants start with 'k'  followed by an uppercase letter
  29.  
  30.  local variables start with a lowercase word
  31.  
  32.  parameters in header files are only named where the name adds to the   
  33.  readability
  34.    eg: dbQuery(dbQuery&) - not needed in copy constructor
  35.  dbfieldSeg(dbField&, unsigned int len)  - len is needed
  36.  
  37.  public functions start with a lowercase letter, 
  38.  private & protected functions start with an Uppercase
  39.  
  40.  User database CONVENTIONS
  41.  dbField members start with an uppercase letter, eg dbChar  LastName;
  42.  
  43.  
  44.  DYNAMIC MEMORY
  45.  Where a dynamically allocated member is "owned" by a class, meaning the
  46.  class is responsible for it's allocation & deallocation, the member has
  47.  // owned
  48.  next to its declaration.
  49.  
  50.  There are rare cases where a method transfers ownership of a member, or
  51.  exposes a pointer. The names of these methods will have "adopt" or
  52.  "expose" in them, or in a comment next to the name (eg: an operator char*).
  53.  
  54.  There are a lot of pointer members in OOFILE which are purely references to
  55.  related classes. Marking relevant pointers with //owned makes it easy to see
  56.  which ones should be cleaned up in destructors.
  57.  
  58. -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  59.  
  60.                ************ CONCEPTS and IDIOMS *************
  61.  
  62. This section tries to summarise some of the c++ techniques I've used. I urge you
  63. to purchase "Effective C++" (see Resources at end) but the following may help if
  64. you are fairly new to C++ and a little confused by some of OOFILE's code.
  65.  
  66. PROTECTED STATIC MEMBERS INSTEAD OF GLOBAL VARIABLES
  67. In any library for general re-use, globals have the potential to cause conflicts
  68. and "pollute the namespace". They also suffer from uncontrolled access - anyone
  69. can fiddle with them. I use Static Class Members instead, which are global
  70. variables belonging to a specific class (eg: dbConnect::currentlyConstructing).
  71. They have to be explicitly qualified by the class name and you can restrict who
  72. has access using either Friend Classes or Friend Functions.
  73.  
  74. -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  75. HANDLE CLASSES and REFERENCE COUNTING
  76. OOFILE_Dictionary and OOFILE_DictRep form a pair, where the outer class forwards
  77. nearly all its function to the inner (except for iteration).
  78.  
  79. This allows multiple copies of OOFILE_Dictionary to point to a single copy of
  80. the actual data, in OOFILE_DictRep, at the cost of some extra forwarding logic.
  81. Note that any copy constructors or assignments that create a new
  82. OOFILE_Dictionary must update the reference count of the DictRep.
  83.  
  84. The forwarding is not as onerous as it may appear - use of inlines reduces it to
  85. little more than one pointer derefence over the normal use of virtual object.
  86.  
  87. -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  88.  
  89. (LAZY) SELF-EXPANDING ARRAYS, INDEXING and C++ OPERATOR OVERLOADING
  90. I've overloaded operator[] (the array index) in three ways for the
  91. OOFILE_Dictionary. Notice that I've provided both unsigned int and signed int,
  92. as well as the named access.
  93.  
  94. There is a minor problem in providing a native unsigned int, without a signed
  95. int version, in that the literal constant 0 is typed as a signed int. By the c++
  96. conversion rules, the literal constant 0 is one trivial conversion away from
  97. either a null pointer to char, or an unsigned int.
  98.  
  99. Thus, the ambiguity cannot be resolved. Providing an operator[] with a signed
  100. int (inlined for performance), gives an operator that can be called with no
  101. trivial conversions. Being a slightly better choice, therefore the compiler is
  102. happy that literal 0 will invoke the [signed int] version.
  103.  
  104. I've made OOFILE_DictRep a "lazy" array in that the default constructor doesn't
  105. declare any space and there is no requirement for users of the class to
  106. explicitly tell it to expand. If you look into the operator[] you'll notice it
  107. performs a range check and does an expansion. The expansion provides a null
  108. pointer in the target cell, so use of an out of range value on the rhs is legal
  109. and detectable:
  110.     myField = mFields[outOfRangeIndex];
  111.     if (myField)...
  112.  
  113. -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  114.  
  115.                ************ LEARNING C++ and RESOURCES *************
  116.  
  117.  
  118. LEARNING c++ QUICKLY
  119. My recommended technique, validated by several others, is to start with Meyers'
  120. "Effective C++" and refer back to a primer or the ARM when you don't understand
  121. something. This forces you to confront the most jarring and dangerous c++ issues
  122. early and helps prevent learning bad habits. As in learning any new language, it
  123. helps immensely to be working on a realistic project.
  124.  
  125. -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  126.  
  127. GENERAL BOOKS
  128. Gamma, Helm, Johnson & Vlissides, "Design Patterns" ISBN 0-201-63361-2
  129. The infamous "Gang of Four" book. The patterns movement is the latest, best hope
  130. for getting some engineering into Software Engineering by documenting portions
  131. of designs in a usable format. EVERBODY should read this book!
  132.  
  133. Lakoff, "Women, Fire and Dangerous Things" ISBN 0-226-46804-6
  134. Subtitled - What Categories Reveal about the Mind - it is a slightly academic 
  135. work on cognitive models, attacking the "objectivist" viewpoint and providing
  136. firm evidence that we categorize things in different ways. The implications for
  137. OO designers are serious - this book helps explain why sometimes we can't find
  138. the "right" objects, or why people differ in their choice of objects.
  139.  
  140.  
  141. C++ BOOKS
  142. Meyers, "Effective C++"  ISBN 0-201-56364-9
  143. very readable, full of simple recipes for adapting from C to c++ or avoiding
  144. common mistakes in c++. I think any serious c++ programmer should be capable of
  145. understanding this book.
  146.  
  147. ARM - Ellis & Stroustrup, "The Annotated C++ Reference Manual" ISBN 0-201-51459-1 
  148. (My copy has April 1994 revision date inside the cover). *the* reference manual
  149. that describes every quirk of the language - the sort of thing you must quote if
  150. you want to pick an argument with compiler writers
  151.  
  152. Lippman, "C++ Primer 2nd ed." ISBN 0-201-54848-8
  153. A rather long-winded primer. If you like succint explanations avoid this and
  154. just buy the ARM, but have a look in at it the bookstore first. It's a very good
  155. introductory book and worth dropping back to if you find the others heavy going.
  156.  
  157. Coplien, "Advanced C++ Programming Styles and Idioms" ISBN 0-201-54855-0
  158. You need to be very competent in c++ to understand this book but it presents
  159. some interesting techniques, particularly if you're into more dynamic designs
  160. that normally associated with c++. I found it a great thought-provoker while
  161. designing the framework.
  162.  
  163. Barton & Nackman, "Scientific & Engineering C++" ISBN 0-201-53393-6
  164. The examples are definitely SciEng oriented but the descriptions of advanced c++
  165. techniques are superb, more readable than Coplien and well-illustrated with
  166. diagrams. The emphasis on templates is probably due to the difference between
  167. Coplien as a 1992 book and this in 1994. A great starting point for ex FORTRAN
  168. and C programmers.
  169.  
  170. Spuler, "C++ and C Debugging, Testing and Reliability" ISBN 0-13-308172-9
  171. A successor to Koenig's "C Traps and Pitfalls" this book combines a list and set
  172. of debugging resources with a very clear list of common c++ errors. Some overlap 
  173. with Meyers' 50 rules occurs, but generally the errors listed are lower level 
  174. simple bugs.
  175.  
  176. Teale, "C++ IOStreams Handbook" ISBN 0-201-59641-5
  177. The only detailed and clear explanation of IOStreams that I've seen or seen 
  178. mentioned. The book documents the older AT&T streams library so there have been a
  179. few minor changes but it is still largely applicable and makes a clear case for
  180. moving to streams.
  181.  
  182. "Taligent's Guide to Designing Programs"  ISBN 0-201-40888-0
  183. an internal style guide that grew. Very good advice on
  184. structuring libraries to minimize impact of change
  185.  
  186.  
  187. OBJECT-ORIENTED DESIGN
  188. Robert Martin, "Designing Object-Oriented C++ Applications Using the Booch Method"  ISBN  0-13-203837-4
  189. A great book that teaches OOA & OOD by example, including the thought processes,
  190. backtracking and refinement of real examples. It discusses the trade-offs in c++
  191. designs and includes metrics for design quality.
  192.  
  193. Walden & Nerson, "Seamless Object-Oriented Software Architecture"  ISBN 0-13-031303-3
  194. Describes the BON method, which grew out of attempts to formalise Eiffel into a
  195. design language. BON offers hope for complex and large projects with compression
  196. of diagrams without loss of readability. The visual notation is paralleled by a
  197. textual form. Martin's book rescues the Booch method from some of the
  198. smoke-and-mirrors that goes into identifying objects, but BON has different
  199. approaches that are worth investigating.
  200.  
  201. DATABASE BOOKS
  202. Cattell (ed) "The Object Database Standard: ODMG-93" ISBN 1-55860-302-6
  203. Clearly written standards document (amazing!). Interesting to note how much OOFILE
  204. resembles their ideas for the "future" c++ binding - this is entirely parallel
  205. evolution of ideas (comfortingly).
  206.  
  207. Loomis, "Object Databases The Essentials" ISBN 0-201-56341-X
  208. Great overview of products and forces in the development of ODBMS technology to the
  209. current state (publication date is 1995). The book covers a lot of issues succintly.
  210.  
  211.  
  212. INTERFACE DESIGN
  213. "Designing Visual Interfaces", Kevin Mullet and Darrell Sano
  214. ISBN 0-13-303389-9
  215.  
  216. This is a BEAUTIFUL little book which "approaches interface design from the perspective of communication-oriented graphic design, industrial design, and architecture."
  217.  
  218. It is full of examples of good and bad interface, discussion of layout (including grids). eg: the 10 pages on grids has 9 illustrations including 4 screen shots.
  219.  
  220. The book includes screens and discussions of standards from Mac, MS Windows, Open Look and Motif. Nobody is spared bouquets or brickbats.
  221.  
  222. This is now my number-one "must buy" for anyone in interface design. It is so clearly written you can use it to explain almost any point of discussion that comes up in trying to explain why a design is good/bad.
  223.  
  224. -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  225.  
  226. INTERNET RESOURCES
  227. The Comp.Object FAQ is a fantastic compilation of Object oriented development
  228. references, definitions and product information. It is available as described
  229. below, and regularly posted to the comp.object news group:
  230.  
  231. Version: 1.0.8
  232. Date:    2/Jun/95
  233.  
  234.  
  235. Author:
  236.   Bob Hathaway
  237.   Geodesic Systems, Inc.
  238.   Cyberdyne Systems Corporation
  239.   rjh@geodesic.com
  240.  
  241.  
  242. Anonymous FTP Sites and Hypertext Server:
  243.   anonymous@zaphod.uchicago.edu:/pub/CompObj6.faq(.Z) (128.135.72.61)
  244.   anonymous@rtfm.mit.edu:/pub/usenet/comp.object/*_Part_*
  245.   http://cui_www.unige.ch/OSG/FAQ/OO-FAQ/index.html
  246.  
  247. Mail Server:  (See also section 1.24)
  248.   mail mail-server@rtfm.mit.edu
  249.   Subject:
  250.   send usenet/comp.object/*
  251.  
  252. Zaphod is preferred over rtfm for anonymous ftp retrieval, as it provides a
  253. single file.  Rtfm contains the FAQ as posted.
  254.  
  255.  
  256.  
  257. The c++ FAQ is specific to c++ although it obviously includes some OOP theory
  258. questions. Read it before you ask beginner's questions in comp.lang.c++.
  259.  
  260.     AUTHOR:        Marshall P. Cline, Ph.D.
  261.             Paradigm Shift, Inc.
  262.             One Park St. / Norwood, NY  13668
  263.             voice: 315-353-6100
  264.             fax:   315-353-6110
  265.             email: cline@parashift.com
  266.  
  267.     AVAILABILITY:    This is available via anonymous ftp
  268.             from: sun.soe.clarkson.edu [128.153.12.3]
  269.             in the file: pub/c++/FAQ
  270.             URL:  ftp://sun.soe.clarkson.edu/pub/c++/FAQ
  271.             and posted regularly in comp.lang.c++
  272.  
  273.