C/C++ Interactive Reference Guide

home *** CD-ROM | disk | FTP | other *** search

/ C/C++ Interactive Reference Guide / C-C++ Interactive Reference Guide.iso / c_ref / csource3 / 137_01 / feb84col.ddj < prev next >

Wrap

Text File | 1979-12-31 | 19.4 KB | 535 lines

.pl 60 .po 0 .. .. "The C/Unix Programmer's Notebook" .. .. DDJ Column #2 as of 19-Sep-83 .. (C) 1983 Anthony Skjellum. All rights reserved. .. For publication in DDJ .. .. .. file (DDJCOL2.WS) created: 24-Nov-83 .. updated: 24-Nov-83 .. updated: 25-Nov-83 .. .. completed: 25-Nov-83 .. .he "C/Unix Programmer's Notebook" by Anthony Skjellum. (C) 1983. For 2/84 DDJ. Introduction .. In the first installment of this column, I proposed a standard for the layout of C code (see DDJ #84, October, 1983.) Significant reader response was received concerning this subject. The vast majority of the letters received were in favor of the concept of a C layout standard. In this column, I will present reader comments concerning the layout standard, and discuss some modifications and additions to the proposed standard based on reader suggestions. .. Some comments were also received concerning my discussion of runtime library and linkage format incompatibilities. Discussion of these points will be left for a future column. Modifying the Proposed Layout Standard I. Questions of White Space .. Several readers took exception to a particular point concerning the proposed layout standard. This was point 4f. which states "No white space character is placed between a keyword (e.g. if) and its parenthesized argument." David D. Clark of State College, Pennsylvania, writes: .. "In general, I like your coding standard suggestions. My only strong objection is your idea to leave out spaces between reserved words [and their arguments]. It makes them look like function invocations." Tim Smith of Evanston, Illinois, notes: .. "...I think that a single space between a function name and the initial opening parenthesis, or after "if's" and "elses", looks better..." Guy Scharf of Mountainview, California writes: .. "4f. I have a strong preference to always put a space between a reserved word (e.g. if, while) and its parenthesized argument. This adds legibility for me." Finally, Charlie Brady of New South Wales, Australia, writes: .. "The only real beef I have with you is the formatting of keywords and their parenthetical expressions. I can see no reason to depart from Kernighan and Ritchie on this point, and a number of reasons for maintaining their convention. Firstly, a flow control construct is semantically distinct from a function call, and a formatting difference is a reasonable way of distinguishing them. Secondly, the formatting difference simplifies the use of a text editor for such tasks as constructing structure charts. Third, your recommendation departs from at least three extant recommended standards, namely Kernighan and Ritchie, Thomas Plum (C Standards and Guidelines, Plum-Hall 1981) and Tim Lang (Formatting C, AUUGN Vol 4, No 1, Jan 1982. Enclosed)." (I want to thank Mr. Brady for including a copy of the Lang article with his letter. The C standard proposed there is very compatible with the one I have proposed.) .. After considering the above remarks, I have come to the conclusion that the space really does serve a useful purpose. Therefore, I suggest that point 4f. should be changed to read: "A single white character is (optionally) placed between a keyword (e.g. if) and its parenthesized argument." (Making the white space character optional is another point for debate.) I think it should be optional, but recommended. I don't think that adding a space for function call invocations would be beneficial, as suggested by Mr. Smith. .. Another question concerning white space insertion comes in connection with argument lists. The original standard does not indicate if spaces should be included. It is my opinion that a comma should be directly adjacent to the argument that it follows, and that a single white space should follow each comma to add legibility. I am also convinced that parentheses should be adjacent to the argument(s) they enclose. Thus (in agreement with Tim Lang's article mentioned above) I would write: x = atan(sin(y)); and not x = atan( sin( y ) ); .. Yet another point not previously mentioned is that binary operators should be delimited by white space. Thus, the following statement lacks sufficient white space: v = sin(ln(1.0+x)); while this expression is properly formed: v = sin(ln(1.0 + x)); .. Finally, section 4 needs to be updated to include a style specification for pointer references. I think that that operators '.' and '->' should not be delimited by spaces from the objects which they act on. This point and the three above are formalized in Figure I. as additions to section 4. .pa ------------------FIGURE I.-------------------- (Under section 4) b. Binary operators (e.g. +, -, / but not '->' and '.') and assignment operators (eg =, *=, &=) are delimited by white space. g. Parentheses should be adjacent to the argument(s) which they enclose. h. A comma is bound to the argument which preceeds and should be followed by a single space. i. Operators such as '->' and '.' (used in pointer references) directly bind to their arguments with no intervening spaces. ---------------------END FIGURE I.-------------------- .. The Lang article points out a circumstance under which point 9g. need not be followed. This occurs when very complicated conditional expressions of the form "keyword (expr)" are split over several lines. For example, instead of using a crowded expression as illustrated in Example 1a., a more readable form is selected (see Example 1b.) Note that in Example 1b. that the parentheses are placed on lines by themselves, since they bracket a multiline expression, much like braces enclose the statements of a block. --------------------Example Ia.--------------------- if((a == 1) && (b == 2) && (c == 3) && ((d == 4) || (d == 5))) { /* operations performed if conditional true */ ... } --------------------End Example Ia.-------------------- --------------------Example Ib.--------------------- if /* we make multi-line expression look like a block */ ( (a == 1) && (b == 2) && (c == 3) && ((d == 4) || (d == 5)) ) { /* operations performed if conditional true */ ... } --------------------End Example Ib.-------------------- .. Another point of minor objection was the tabulation method specified by the standard (point 1a.). Steve Newberry of Los Altos, California, states: .. "Upon one point I do feel compelled to argue with you, and that is the tab convention: The DEPTH of the tab stop on a given page is of far less significance to the readability of that page than is the CONSISTENCY of the depth. I REALLY don't want to use different size tabs on the same page." Tim Smith writes: "I personally follow most all of his suggestions on how to actually format the code on the line and page, with only two exceptions. I ALWAYS use 4-space tab stops..." .. I agree that having a single tab size is the preferable way to write C code. Standard tabs give more openness to the code, and make various parts of a program easier to pick out. My rationale for large horizontal tabbing is the same as for vertical tabbing. I want the program's significant portions to stand out. However, I propose adding point 1b. to the standard: "4-space tabs may be used in lieu of standard tabs in cases where a sub-program includes highly nested segments." I would also include point 1c.: "Only one of the two tabbing conventions should be employed in any given program module." .. Some currently available screen editors provide a feature called horizontal scrolling. With horizontal scrolling, the user views a window of his file in both the vertical and horizontal directions. Thus, files with lines longer than the display device may be handled intelligently. Under such circumstances, there is no real disadvantage to using standard tabs to any desired nesting depth, which is permitted by point 1a. of the proposed standard. II. Other corrections. .. Charlie Brady pointed out an unnecessary point in section 3 (point 3e) which stated: "When a null block is used (e.g. "{}"), it may appear on the same line as other statements (e.g. do {} while(expr);). He writes: .. "Another minor point of disagreement concerns the use of the null block ({}). This is never necessary, and I believe that the null statement (;) is clearer. It should be emphasised that the null statement deserves a line of its own. Your example: do {} while(expr); is more simply written while (expr) ; .. In accordance with Mr. Brady's remark, I propose replacing point 3e with the following: "The null block ({}) can always be avoided. Instead of a null block, use the null statement." I also would add point 3f#ii.: "The null statement is always on a line by itself." III. Documentation Standards .. In addition to a code layout standard, James Halstead of Joliet, Illinois, has proposed a basic documentation standard. He writes: .. "...I strongly suggest that the original standards one through nine be renumbered two through ten so that the first and foremost standard may be inserted." The documentation standard suggested by Mr. Halstead is presented in Figure II. and I think it should be included in my proposed standard. However, I have decided to number the documentation standard as section 0. in order to preserve the numbering of the current sections. (Slight additions which I made include an asterisk to indicate my addition.) .pa -------------------FIGURE II.------------------- 0. Identification Description (I.D.) information must appear at the beginning of each C language source file. a. The recommended format is: i. Begin comment (/*). ii. Space. iii. Title (identification name normally = filename). * iv. Sub-title (ie what program system does this file belong to). v. Space. vi. Classification (see below). vii. Year. viii. Owner. ix. Status (see below). * x. Current Version number and brief history. xi. Date. xii. Functional/Structural Description in brief. * xiii. Portability synopsis. * xiv. Space. xv. End Comment (*/). * xvi. Space. b. The program classification (vi.) is one of the following: i. public-domain. ii. copyright. * iii. copyright: released for non-commercial purposes. iv. unclassified. v. secret. vi. no classification. c. The program status (ix.) is one of the following: i. outline. ii. draft. iii. test (alpha, beta etc.) iv. release. -------------------END FIGURE II.-------------------- .pa .. In addition to Section 0., I think a basic documentation standard is in order for functions as well. Such a standard is presented in Figure III. I have placed this under section 10, since I think of function documentation is a separate task from module documentation as described in section 0. -------------------FIGURE III.------------------- 10. Each function should contain the following minimum documentation: a. A general explanation of the function performed. b. Its name, and a description of its arguments including their types, and legal values. c. A description of the functional return value, if any. d. A list of non-standard functions used by the function. e. A list of external variables used and/or modified by the function. f. A description of the error handling characteristics of the function. g. A valid calling sequence example, if practical. -------------------END FIGURE III.-------------------- IV. Other proposals .. Several other readers made suggestions for the standard. I think that Tim Smith proposes several which merit discussion. They are presented here with the point numbers they receive as part of the standard: (5c). Don't nest comments, even if your preprocessor/compiler allows it. (6f). If there are many declarations, whether on one line or many, alphabetize them. (9g). Restrict variable and function names to 7 well-chosen characters, even if your compiler allows more. Steve Newberry writes the following about standards: .. "I applaud your interest in establishing a standard format convention for C programs. However I feel that your effort would have more impact if tied to support of Tom Plum's book C Programming Standards and Guidelines, Version U (Unix and offspring), Edition 3: Jan. '82. Presented in this manner, your proposed formatting standard would be seen as a consistent extension of a more general set of standards already in wide circulation." Other points of View Although most readers were favorable to the idea of a C format standard, Douglas M. Potter of Seattle, Washington, writes: "I afraid I don't see much advantage of your proposed standard over theirs [Kernighan and Ritchie]. In both cases, the size of the ident is too large, I always run out of room on the right side with a tab sized ident. I also find that nobody uses enough white space." John F. Draffen of Texas City, Texas, wrote me a detailed letter on why he didn't like the idea. He writes: "I am writing to express my objections...In the first place I do not think a standard of this type is either necessary or desirable. The layout has nothing to do with portability which to my mind is the only excuse for a standard. It seems to me that it is hard enough to get people to agree on necessary standards." "In the second place I do not agree with many of your suggestions on style. One of the nice things about C that it shares with Fortran is it's relative conciseness. I do not like to see code strung out unnecessarily. C does not interject unnecessary constructions, and I think that introducing unnecessary white space, excessive indentation and meaningless comments is a kind of gingerbread that we can do without." Mr. Draffen's style philosophy is listed in Figure IV. --------------------FIGURE IV.-------------------- 1. Punctuation should be used sparingly. The insertion of unnecessary white space should be avoided. 2. Block structure should be used indicated by indentation. Excessive indentation should be avoided. 3. Comments and program code should be separated. Comments on the same line as code should be displaced far enough to the right that they do not obscure the code. 4. Comments should be meaningful. Comments that do no more than repeat what has already been said by the code should be avoided. ----------------------END FIGURE IV.--------------------- I don't really agree with Mr. Draffen on several counts. First and foremost is that portability is not the sole subject of importance in programming. The ability to maintain, understand, correct and enhance code is of great importance. To understand someone else's code, (or your own code at a later date) requires some degree of formatting. Comments which seem less than essential to the programmer must sometimes be included for the sake of others. This is immensely important. It is often difficult for a programmer to know how to comment his code, since he usually can not know the level of sophistication of later readers. Thus, it is often better to include a few extra comments, than to comment code sparsely. I suggested in my previous column that users should maintain their own code in the form that they prefer. However, code distributed to others could (and should) meet some minimum standard of neatness (ie formatting) and presentation. Some of this can be provided by a beautifier but most must be done by the programmer himself. As one final note on C layout, I'm including an insightful paragraph which Tim Smith included his letter. It suggests why so much C code is so poorly formatted and commented: "I don't think, however, that you will ever get Unix wizards to follow these recommendations. I should have noted that I use Skjellum-like conventions when I'm writing micro-based applications. When I'm maintaining Unix sources I stick with the standard Unix conventions, which are pretty much K & R [Kernighan and Ritchie] standard. Unix whiz's think that aligning curly braces is irrelevant, since "vi", the editor which 90% of them use, will always let you find the top or bottom match for any brace automatically. Also, and probably more important, Unix system guys always debug by staring at their CRT's, never from printouts (that's for COBOL programmers), and the goal is to reduce the number of lines of a function, so that as much of it as possible will fit on a screen. Seeing a WHOLE LINE taken up by just an opening brace must drive them whacko, and some of them will even close blocks on the end of a line of code (yecch!)" Conclusion .. In this column, I have presented additions and corrections to the proposed layout standard, based on reader response. I have also presented the opposing point of view. Most of the letters received were positive, so it was difficult to include more dissenting remarks. I want to thank those who sent in their comments about the standard.