home *** CD-ROM | disk | FTP | other *** search
/ NetNews Usenet Archive 1992 #19 / NN_1992_19.iso / spool / comp / lang / perl / 5532 < prev    next >
Encoding:
Internet Message Format  |  1992-08-26  |  7.6 KB
  1. Path: sparky!uunet!usc!news!netlabs!lwall
  2. From: lwall@netlabs.com (Larry Wall)
  3. Newsgroups: comp.lang.perl
  4. Subject: Re: Perl language formatting conventions?
  5. Message-ID: <1992Aug27.042932.3143@netlabs.com>
  6. Date: 27 Aug 92 04:29:32 GMT
  7. References: <1992Aug25.152315.20630@news.eng.convex.com> <BtJux7.CEp@news.cso.uiuc.edu> <1992Aug25.224912.1775@news.eng.convex.com>
  8. Sender: news@netlabs.com
  9. Distribution: comp
  10. Organization: NetLabs, Inc.
  11. Lines: 214
  12. Nntp-Posting-Host: scalpel.netlabs.com
  13.  
  14. In article <1992Aug25.224912.1775@news.eng.convex.com> tchrist@convex.COM (Tom Christiansen) writes:
  15. : Here's the Berkeley style guide for comparison.  I don't personally
  16. : use all of them (i.e. I use 4-space indents and test pointers with 
  17. : a raw "if (p)') but surprisgnly, I find that many I do use even 
  18. : though I had never read this guide.
  19.  
  20. I also use 4-space indent, in case you hadn't noticed.  :-)
  21.  
  22. I'm gonna comment on some of these C thingies, so if you're here to read
  23. about Perl formatting you can type "n" now.
  24.  
  25. : /*
  26. :  * Macros are capitalized, parenthesized, and should avoid side-effects.
  27. :  * If they are an inline expansion of a function, the function is defined
  28. :  * all in lowercase, the macro has the same name all in uppercase. If the
  29. :  * macro needs more than a single line, use braces.  Put a space before
  30. :  * the backslashes.
  31. :  */
  32. : #define    MACRO(x, y) { \
  33. :     variable = (x) + (y); \
  34. :     line two; \
  35. : }
  36.  
  37. I'd line up the backslashes--it's an awful lot easier to see when you've
  38. left one out.
  39.  
  40. : /* Enum types are capitalized. */
  41. : enum enumtype { ONE, TWO } et;
  42.  
  43. Those are enum *values*, not types.
  44.  
  45. : /*
  46. :  * When declaring variables in structures, declare them sorted by use, then
  47. :  * by size, and then by alphabetical order.  The first category normally
  48. :  * doesn't apply, but there are exceptions.  Each one gets its own line.
  49. :  * Put a tab after the first word, i.e. use "int^Ix;" and "struct^Ifoo *x;".
  50. :  *
  51. :  * Major structures should be declared at the top of the file they are
  52. :  * used in, or in separate header files, if they are used in multiple
  53. :  * source files. Use of the structures should be by separate declarations
  54. :  * and should be "extern" if they are declared in a header file.
  55. :  */
  56. : struct foo {
  57. :     struct    foo *next;    /* List of active foo */
  58. :     struct    mumble amumble;    /* Comment for mumble */
  59. :     int    bar;
  60. : };
  61. : struct foo *foohead;        /* Head of global foo list */
  62.  
  63. What they didn't say was that you sort the variables in structures
  64. by *decreasing* size.  This makes for the most compact representation
  65. without the compiler cheating on the semantics of C.
  66.  
  67. I also think it's silly to put the tab between "struct" and the type
  68. name.  I'm of two minds as to where to put the tab on pointers to
  69. structures.  Sometimes I put
  70.  
  71.     struct foo    *next;
  72.  
  73. and sometimes
  74.  
  75.     struct foo*    next;
  76.  
  77. depending on how heavily I'm into denial over C's type syntax.  I've
  78. been doing more of the latter lately.
  79.  
  80. :     while ((ch = getopt(argc, argv, "abn")) != EOF)
  81. :         switch (ch) {        /* Indent the switch. */
  82. :         case 'a':        /* Don't indent the case. */
  83. :             aflag = 1;
  84. :             /* FALLTHROUGH */
  85. :         case 'b':
  86. :             bflag = 1;
  87. :             break;
  88. :         case 'n':
  89. :             num = strtol(optarg, &ep, 10);
  90. :                         if (num <= 0 || *ep)
  91. :                                 err("illegal number -- %s", optarg);
  92. :             break;
  93. :         case '?':
  94. :         default:
  95. :             usage();
  96. :         }
  97.  
  98. This is evil.  Any dangled statement longer than one line should be
  99. enclosed in braces.  One of the reasons I require braces in Perl...
  100.  
  101. :     /*
  102. :      * Space after keywords (while, for, return, switch).  No braces are
  103.  
  104. Yes.  I don't want my keywords looking like functions, and vice versa.
  105.  
  106. :      * used for single statement block.
  107. :      *
  108. :      * Forever loops are done with for's, not while's.
  109. :      */
  110. :     for (;;)
  111. :         stmt;
  112.  
  113. Yes, I find the (;;) visually distinctive for a distinctive idea, and
  114. C needs all the visual distinctiveness it can muster.
  115.  
  116. :     /*
  117. :      * Try to put shorter part first.  The closing and opening braces
  118. :      * go on the same line as the else.
  119. :      */
  120. :     if (test)
  121. :         stmt;
  122. :     else if (bar) {
  123. :         stmt;
  124. :         stmt;
  125. :     } else
  126. :         stmt;
  127.  
  128. I prefer my else's to line up, but that's just taste.  Whether to put
  129. the shorter part first depends on how easy it is to express the conditional
  130. in an understandable way.  Sometimes I go so far as to change the name
  131. of a Boolean variable so that I can put the right branch first without
  132. extra !'s.  The real trick is to find the opposite name for the Boolean
  133. variable without just putting "no" on the front of it...  :-)
  134.  
  135. :     /* No space after function names. */
  136. :     if (error = function(a1, a2))
  137. :         exit(error);
  138.  
  139. Yes.  I don't want my keywords looking like functions, and vice versa.
  140. The parens of a function are an intrinsic part of the function call in C.
  141. Pretending that a function name is a unary operator prefixing an ordinary
  142. parenthesized list is bogus to me.
  143.  
  144. :     /*
  145. :      * Unary operators do not require spaces, binary operators do.
  146. :      * Try not to use too many parenthesis unless the statement is
  147. :      * really confusing without them.
  148. :      */
  149. :     a = b->c[0] + ~d == (e || f) || g && h ? i : j >> 1;
  150. :     k = l & FLAGS;
  151.  
  152. Hmm, sometimes you just need to break up an expression and indent it
  153. reasonably.  Sometimes you can omit the spaces on a binary operator to
  154. imply precedence:
  155.  
  156.     a + b*c + d;
  157.  
  158. :     /*
  159. :      * Exits should be 0 on success, and 1 on failure.  Don't denote
  160. :      * all the possible exit points, using the integers 1 through 300.
  161. :      */
  162. :     exit(0);    /* Avoid obvious comments such as "Exit 0 on success." */
  163.  
  164. Obviously, you have to get along with Unix here, but for return values
  165. I prefer "success" to be associated with "truth".  You can pass the
  166. (presumably infrequent) error information by some other mechanism when
  167. necessary, and then you won't be tempted to shoehorn too much meaning
  168. into a simple-minded integer.
  169.  
  170. : /*
  171. :  * If a function type is declared, it should be on a line
  172. :  * by itself preceeding the function.
  173. :  */
  174. : static char *
  175. : function(a1, a2, a3, a4)
  176.  
  177. Yes, and notice that they're doing a line break where earlier I said
  178. I liked doing a tab--after the *.  But of course, the reason is
  179. rather different here.  We want to be able to search using /^function.
  180.  
  181. :     int a1, a2, a4;    /* Declare ints too. */
  182.  
  183. I'd put these on separate lines.
  184.  
  185. :     /*
  186. :      * Casts and sizeof's are not followed by a space.  NULL is any
  187. :      * pointer type, and doesn't need to be cast, so use NULL instead
  188. :      * of (struct foo *)0 or (struct foo *)NULL.
  189.  
  190. This can break when passing arguments to functions.  I prefer to use
  191. typed NULLish thingies for documentation purposes consistently, and
  192. then I don't forget to cast them when I use them as function
  193. arguements.  So I end up with Nullch, Nullfp, etc, or in the general
  194. case, Null(FOO*).
  195.  
  196. :      * Also, test pointers against NULL, i.e. use:
  197. :      *
  198. :      *     (p = f()) == NULL
  199. :      * not:
  200. :      *    !(p = f())
  201.  
  202. NO!  This is a throw-back to Pascal, in which conditionals require
  203. Boolean values and only Boolean values.  C blesses the notion that many
  204. types can be used as Boolean values.  C++ carries this even further,
  205. and essentially provides that any user-defined type for which it makes
  206. sense can be set up to be used as a Boolean value.
  207.  
  208. :       *
  209. :      * Routines returning void * should not have their return values cast
  210. :      * to any pointer type.
  211. :      */
  212. :     if ((four = malloc(sizeof(struct foo))) == NULL)
  213. :         return (NULL);
  214.  
  215. That's contrary to usual industry practice.  Fortunately the necessity
  216. for it goes away in C++.
  217.  
  218. :     if ((six = (int *)overflow()) == NULL)
  219. :         return (NULL);
  220. :     return (eight);
  221.  
  222. Of what earthly good are the parens around a return value, other than to
  223. make Yet Another Keyword look like a function?
  224.  
  225. Well, enough of that.  Back to your regularly scheduled programming.
  226.  
  227. Larry
  228.