home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / PRESPM.ZIP / C_STYLE.TXT next >
Text File  |  1991-04-15  |  7KB  |  152 lines
  1.  
  2.  
  3.  The somewhat unorthodox 'C' style used in this program was developed
  4.  for reasons of clarity and portability.  The three primary differences
  5.  from commonly employed styles that you will note are:
  6.  
  7.  
  8.  1.  There is no use of the "//" comment delimiter for comments at
  9.      the end of a line.  This practice does not, unfortunately,
  10.      conform to the ANSI 'C' standard.  However, it is still a nuisance
  11.      to have to add the closing asterisk-slash at the end of comment
  12.      lines, so the style you see here was adopted.  It has the 
  13.      advantage that no delimiters are required at the end of the
  14.      lines in block comments, and it visually separates the comments from 
  15.      the rest of the program source.  
  16.  
  17.      (The opening line is slash-asterisk-backslash;
  18.      the closing line is backslash-asterisk-slash, 
  19.      and all intervening lines are verticalbar-asterisk-verticalbar.)   
  20.  
  21.      /*\
  22.      |*| Longer multi-line comments are entered like this; there is
  23.      |*| no need to place closing comment delimiters at the right on a
  24.      |*| line-by-line basis.  This style is derivative from a similar  
  25.      |*| style often used by Microsoft in sample code.  The reason for
  26.      |*| this particular style is primarily one of personal esthetics --
  27.      |*| I think it makes the comments stand out a little better from the
  28.      |*| code, and it looks more symmetrical.
  29.      \*/
  30.  
  31.      /*\ This is short one-liner comment.
  32.      \*/
  33.  
  34.  2.  Function prototypes and definitions are in the "new" ANSI
  35.      style.  One advantage the old style had was that you could
  36.      see the parameters one to a line, and associate short
  37.      descriptions of each parameter, as in:
  38.  
  39.          int oldfoo(a,b,c) 
  40.              int a;        // here is a comment about "a"
  41.              char *b;      // a useful description of "b" goes here
  42.              long c;       // this is a succinct explanation of c 
  43.              {
  44.      
  45.      Whereas, in the "new" ANSI style, this is usually coded as:
  46.  
  47.          int newfoo(int a, char *b, long c) { 
  48.  
  49.      There didn't seem to be any *nice* place to put the terse, yet
  50.      valuable, half-line descriptions of the use or meaning of the
  51.      function's arguments.  The convention used herein follows the
  52.      dictates of the new ANSI style, while retaining the readability
  53.      advantages of the old, as in:
  54.  
  55.          int myfoo
  56.              ( int a        /* here is a comment about "a"           */
  57.              , char *b      /* a useful description of "b" goes here */
  58.              , long c       /* this is a succinct explanation of c   */
  59.              )
  60.              {
  61.  
  62.                           
  63.  3.  Presentation Manager* programs are characterized by nested calls
  64.      to functions with horribly long names, containing "hungarianized"
  65.      parameters with even longer names.  Indentation styles that 
  66.      were appropriate for *nix programs with short variable names no 
  67.      longer enhance the clarity of the program;  you get a jumble of 
  68.      lines that are too long to be conveniently read online, with lines 
  69.      that have been broken at arbitrary places so that they "fit."  
  70.  
  71.      The approach taken here is to separate every parenthesis and
  72.      semicolon by a space from its neighboring tokens, except for the
  73.      parentheses around a cast.  (This part I picked up from Petzold's
  74.      examples.)  
  75.  
  76.      When a complete statement can fit on a single line, it is just left 
  77.      like that.  But when it won't fit all on one line (which happens 
  78.      frequently) then the line is split at a logical syntactic boundary, 
  79.      and paired delimiters are shown indented at the same level. 
  80.  
  81.      Indentation levels are a standard four characters everywhere, 
  82.      (a seven year old article in the Communications of the ACM presented
  83.      results of a study which showed, for the conditions they described,
  84.      that indenting four spaces is optimal from the standpoint of user 
  85.      readability) and tabs are not used.  (It seems that everyone's editor 
  86.      handles the tabs differently, which reduces the portability of the 
  87.      "readability" of the code).  Part of this is motivated by a desire
  88.      to adopt a style that can easily be handled by supporting editor
  89.      macros and other external utilities.
  90.  
  91.      The list-separation delimiters (commas) in a vertically-presented
  92.      list appear BEFORE the item that follows, rather than AFTER
  93.      the preceding item in the list.  This style thus presents a list
  94.      either all on one line (horizontally), or vertically with only one
  95.      item on each separate line.  The visual structure thus parallels
  96.      the program structure, which is the whole idea behind coding for
  97.      clarity with indentation.  It also turns out to be easier to edit, 
  98.      and to use parts of one program as models for another.
  99.  
  100.      Thus, for example, a WinCreateStdWindow() call would look like:
  101.  
  102.          hwndFrame = WinCreateStdWindow 
  103.              ( HWND_DESKTOP       /*  Desktop window is parent.       */
  104.              , 0L                 /*  Frame style                     */
  105.              , &flCreate          /*  Frame control flag              */
  106.              , szMyClassName      /*  Window class name               */
  107.              , szMyWindowTitle    /*  Window title                    */
  108.              , 0L                 /*\ A really long comment for a 
  109.                                   |*|     parameter would look like this.
  110.                                   \*/
  111.              , NULL               /*  Resource is in .EXE file        */
  112.              , ID_MAINWND         /*  Frame window identifier         */
  113.              , &hwndClient        /*  Client window handle            */ 
  114.              ) ;
  115.       
  116.  
  117.      A "for" loop with long clauses would be indented as:
  118.  
  119.          for ( pctiCurr =  (*pctiHead).pctiCTINext   
  120.              ; pctiCurr != pctiHead && (*pctiCurr).hwndCTI != hwndControl
  121.              ; pctiCurr =  (*pctiCurr).pctiCINext 
  122.              )  
  123.              { 
  124.              /*\ Traverse linked list
  125.              \*/ 
  126.              ...
  127.              }
  128.  
  129.  
  130.      A structure definition would be coded as:
  131.  
  132.          typedef struct DBINFO_ 
  133.              { PDBINFO pdbiDBINext   /* points to next list node     */
  134.              ; PDBINFO pdbiDBIPrev   /* points to prev list node     */
  135.              ; HWND    hwndDBI       /* dialog box's window handle   */
  136.              ; PFNWP   pfnwpDBIProc  /* dialog box's orig winproc    */
  137.              ; CTINFO  ctiDBICTHead  /* head of a list of controls   */
  138.              ; 
  139.              } 
  140.              DBINFO ;
  141.  
  142.  
  143.  I hope that these styles will make Presentation Manager programs
  144.  easier to read, and that it will not be hard for readers to adjust 
  145.  to the stylistic differences.  
  146.  
  147.  24JUN90
  148.  Brian Buck
  149.  
  150. * Presentation Manager is trademark of International Business Machines Corporation.
  151.  
  152.