![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to code_cnvntns.c CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSD / ingres / doc / other|
Return to code_cnvntns.c CVS log | Up to [CSRG BSD Unix] / 43BSD / ingres / doc / other |
1.1 root 1: # include "/usr/sys/param.h"
2: # include <sccs.h>
3:
4: /*
5: ** CODE_CNVNTNS.C -- A Program to Display the INGRES Coding Style
6: **
7: ** This hunk of code does virtually nothing of use. Its main
8: ** purpose is to demonstrate the "official" ingres coding style.
9: **
10: ** This demonstrates comments. There should be a block comment
11: ** at the beginning of every file and/or procedure to explain
12: ** the function of the code. Important information to put here
13: ** includes the parameters of the routines, any options that the
14: ** user may specify, etc.
15: **
16: ** The first line of the comment should be a one-line description
17: ** of what's going on. The remainder should be more detailed.
18: ** Blank lines should separate major points in the comments. In
19: ** general, ask yourself the question, "If I didn't know what this
20: ** code was, what it was for, how it fit in, etc., and if I didn't
21: ** even have the documentation for it, would these comments be
22: ** enough for me?"
23: **
24: ** Some general guidelines for the code:
25: **
26: ** ***** GENERAL SYNTAX *****
27: **
28: ** - Commas and semicolons should always be followed by a space.
29: ** Binary operators should be surrounded on both sides by
30: ** spaces. Unary operators should be in direct contact
31: ** with the object that they act on, except for "sizeof",
32: ** which should be separated by one space.
33: **
34: ** - Two statements should never go on the same line. This includes
35: ** such things as an if and the associated conditionally
36: ** executed statement.
37: ** In cases such as this, the second half of the if
38: ** should be indented one tab stop more than the if. For
39: ** example, use:
40: ** if (cond)
41: ** statement;
42: ** never:
43: ** if (cond) statement;
44: ** or:
45: ** if (cond)
46: ** statement;
47: **
48: ** - Braces ({}) should (almost) always be on a line by them-
49: ** selves. Exceptions are closing a do, and terminating
50: ** a struct definition or variable initialization. Braces
51: ** should start at the same indent as the statement with
52: ** which they bind, and code inside the braces should be
53: ** indented one stop further. For example, use:
54: ** while (cond)
55: ** {
56: ** code
57: ** }
58: ** and never:
59: ** while (cond)
60: ** {
61: ** code
62: ** }
63: ** or:
64: ** while (cond) {
65: ** code
66: ** }
67: ** or:
68: ** while (cond)
69: ** {
70: ** code
71: ** }
72: ** or anything else in that line. Braces which match
73: ** should always be at the same tab stop.
74: **
75: ** - Do statements must always be of the form:
76: ** do
77: ** {
78: ** code;
79: ** } while (cond);
80: ** even if "code" is only one line. This is done so that
81: ** it is clear that the "while" is with a do, rather than
82: ** a standalone "while" which is used for the side effects of
83: ** evaluation of the condition.
84: **
85: ** - There should always be a space following a keyword (i.e.,
86: ** for, if, do, while, switch, and return), but never
87: ** between a function and the paren preceeding its
88: ** arguments. For example, use:
89: ** if (i == 0)
90: ** exit();
91: ** never:
92: ** if(i == 0)
93: ** exit ();
94: **
95: ** - Every case in a switch statement (including default) should
96: ** be preceeded by a blank line. The actual word "case" or
97: ** "default" should have the indent of the switch statement plus
98: ** two spaces. It should be followed by a space (not a
99: ** tab) and the case constant. Multiple case labels on
100: ** a single block of code should be on separate lines, but
101: ** they should not be separated by blank lines. The
102: ** switch statement should in general be used in place of
103: ** such constructs as:
104: ** if (i == 1)
105: ** code1;
106: ** else if (i == 34)
107: ** code2;
108: ** else if (i == -1643)
109: ** code3;
110: ** which can be more succinctly stated as:
111: ** switch (i)
112: ** {
113: ** case 1:
114: ** code1;
115: ** break;
116: **
117: ** case 34:
118: ** code2;
119: ** break;
120: **
121: ** case -1643:
122: ** code3;
123: ** break;
124: ** }
125: ** In point of fact the equivalent switch will compile
126: ** extremely efficiently. (Note that if you had some
127: ** instance where you could not use a case, e.g., checking
128: ** for i < 5, else check for j > 3, else whatever, then
129: ** the above ("if") code is in the correct style. However,
130: ** if (i < 5)
131: ** code1;
132: ** else
133: ** if (j > 3)
134: ** code2;
135: ** else
136: ** code3;
137: ** is acceptable.
138: **
139: ** - A blank line should separate the declarations and the code
140: ** in a procedure. Blank lines should also be used freely
141: ** between major subsections of your code. The major
142: ** subsections should also have a block comment giving
143: ** some idea of what is about to occur.
144: **
145: ** ***** PREPROCESSOR USAGE *****
146: **
147: ** - Fields of #defines and #includes should line up. Use:
148: ** # define ARPA 25
149: ** # define MAXFIELDS 18
150: ** and not:
151: ** #define ARPA 25
152: ** #define MAXFIELDS 18
153: ** Conditional compilation (#ifdef/#endif) should be used
154: ** around all trace information, timing code, and code
155: ** which may vary from version to version of UNIX. See
156: ** the code below for an example of conditional compila-
157: ** tion use.
158: **
159: ** ***** VARIABLES AND DECLARATIONS *****
160: **
161: ** - Defined constants (defined with the # define feature) must
162: ** be entirely upper case. The exceptions to this are
163: ** compilation flags, which begin with a lower case "x",
164: ** and some sub-types for parser symbols. In any case,
165: ** the majority of the symbol is upper case.
166: **
167: ** - Global variables should begin with an upper case letter and
168: ** be otherwise all lower case. Local symbols should be
169: ** entirely lower case. Procedure names are all lower
170: ** case. The only exception to this is the trace routine
171: ** "tTf". You should avoid user non-local symbols (globals
172: ** or # define'd symbols) which are one character only;
173: ** it is impossible to distinguish them. Capitalization
174: ** may be used freely inside global names so long as they
175: ** are primarily lower case; for example, "ProcName" is
176: ** an acceptable name (and preferred over either Proc_name
177: ** or Procname).
178: **
179: ** - Use descriptive variable names, particularly for global var-
180: ** iables. "IEH3462" tells me nothing; nor does "R". On
181: ** the other hand, "Resultid" tells me quite a lot,
182: ** including what it might be, where I might go to see
183: ** how it is initialized, etc. Try not to use variables
184: ** for multiple purposes. Variable names like "i" are
185: ** acceptable for loop indices & temporary storage
186: ** provided that the value does not have long-term
187: ** semantic value.
188: **
189: ** - When the storage structure or type of a variable is
190: ** important, always state it explicitly. In particular,
191: ** include "auto" if you are going to take the address
192: ** of something using the ampersand operator (so that
193: ** some wayward programmer doesn't change it to register),
194: ** and declare int parameters as int instead of letting
195: ** them default.
196: **
197: ** ***** GENERAL COMMENTS *****
198: **
199: ** - It is quite possible to name a file "printr.c" and then
200: ** put the code for "destroydb" in it. Try to arrange
201: ** the names of your files so that given the name of a
202: ** routine, it is fairly easy to figure out which file
203: ** it is in.
204: **
205: ** - Sometimes it is really pretty much impossible to avoid doing
206: ** something tricky. In these cases, put in a comment
207: ** telling what you are doing and why you are doing it.
208: **
209: ** - Try to write things that are clear and safe, rather than
210: ** things which you think are easier to compile. For
211: ** example, always declare temporary buffers as local,
212: ** rather than as global. This way you can another
213: ** routine accidently when it still had useful info
214: ** in it.
215: **
216: ** ***** COMMENTS *****
217: **
218: ** - The importance of comments cannot be overemphasised.
219: ** INGRES is primarily a research vehicle rather than
220: ** a program product. This means that there will be
221: ** many people pouring over your code, trying to
222: ** understand what you have done & modify it to do
223: ** other things. Try to make life easy for them &
224: ** maybe they will be nice to you someday.
225: **
226: ** - Try to keep an idea of the flow of your program. Put
227: ** block comments at the beginning of major segments,
228: ** and use one-line comments at less major junctures.
229: ** A person viewing your code at ten paces should be
230: ** able to tell where the major segments lay.
231: **
232: ** - The preferred format for block comments is to begin with
233: ** a line containing slash-star alone, followed by a
234: ** number of lines all beginning star-star containing
235: ** the comment, and terminating with a line containing
236: ** star-slash alone. Comments without the double-star
237: ** at the beginning of each line should be avoided,
238: ** since it makes the comments seemingly disappear into
239: ** the body of the code.
240: **
241: ** - The beginning of each routine should have a comment block
242: ** in parametric form as demonstrated below. The fields
243: ** "Parameters", "Returns", and "Side Effects" should
244: ** be considered mandatory. Mark parameters as being
245: ** (IN), (IN/OUT), or (OUT) parameters, depending on
246: ** whether the parameter is used only to transmit infor-
247: ** mation into the routine, in and out of the routine,
248: ** or only to return information; the default is (IN).
249: **
250: ** Remember, it is easy to write totally incomprehensible code in
251: ** C, but we don't go in for that sort of thing. It isn't too
252: ** much harder to write brilliantly clear code, and the code is
253: ** worth a lot more later.
254: **
255: ** For efficiency reasons, you should always use register variables
256: ** when possible. A simple and extremely effective tip is to define
257: ** a register variable, and assign an oft-used parameter to it,
258: ** since it is particularly inefficient to reference a parameter.
259: ** Another particularly inefficient operation is referencing arrays
260: ** of structures. When possible, define a register pointer to the
261: ** structure, and then say:
262: ** struct xyz structure[MAX];
263: ** register struct xyz *p;
264: ** ...
265: ** for (i = 0; i < MAX; i++)
266: ** {
267: ** p = &structure[i];
268: ** p->x = p->y + p->z;
269: ** (diddle with p->???)
270: ** }
271: ** and not:
272: ** struct xyz structure[MAX];
273: ** ...
274: ** for (i = 0; i < MAX; i++)
275: ** {
276: ** Structure[i].x = Structure[i].y + Structure[i].z;
277: ** (diddle with Structure[i].???)
278: ** }
279: ** Remember, the nice things about register variables is that they
280: ** make your code smaller and they run faster. It is hard to
281: ** lose with registers. There are three restrictions which you
282: ** should be aware of on register variables, however. First,
283: ** The only types which may be registers are int's, char's,
284: ** and pointers. Second, there may only be three register
285: ** variables per subroutine. Third, you may not take the address
286: ** of a register variable (i.e., you may not say "&i" if i is
287: ** typed as a register variable).
288: **
289: ** Usage:
290: ** example [flags] argument
291: **
292: ** Positional Parameters:
293: ** argument -- this gets echoed to the standard
294: ** output.
295: **
296: ** Flags:
297: ** -n -- don't put a newline at the end.
298: ** -x -- don't do anything.
299: ** -b -- echo it with a bell character.
300: **
301: ** Return Codes:
302: ** 0 -- successful
303: ** else -- failure
304: **
305: ** Defined Constants:
306: ** XEQ1 -- maximum number of simultaneous equijoins.
307: **
308: ** Compilation Flags:
309: ** xTRACE -- enable trace information
310: **
311: ** Trace Flags:
312: ** 5 -- general debug
313: ** 6 -- reserved for future use
314: **
315: ** Compilation Instructions:
316: ** cc -n example.c
317: ** mv a.out example
318: ** chmod 755 example
319: **
320: ** Notes:
321: ** These comments don't apply to the code at all,
322: ** since this is just an example program.
323: ** Also, it is wise to avoid this many comments
324: ** except at the head of main programs and
325: ** at the head of major modules. For example,
326: ** this sort of commenting is appropriate at
327: ** the top of ingres.c (system startup) and
328: ** view.c (virtual view subsystem), but not
329: ** in small utility routines, e.g., length.c.
330: ** This sort of routine should be limited to
331: ** "Parameters:", "Returns:", "Side Effects:",
332: ** and anything else that seems relevant in
333: ** that context.
334: ** A fairly large comment block should exist at the
335: ** top of modules [files] which contain many
336: ** procedures; this block should clarify why
337: ** the procedures are grouped together, that
338: ** is, their common purpose in life. A small
339: ** block should occur at the top of each
340: ** procedure explaining details of that proce-
341: ** dure.
342: ** Procedures should be on separate pages (use the
343: ** form feed character, control-L).
344: ** A program will help you generate this comment block.
345: ** In ex, go to the line where you want to insert
346: ** a block and say "so /mnt/ingres/comment". It
347: ** will ask you for a block type, e.g., "main"
348: ** for main program, "modfn" for a file which
349: ** contains only one function, "function" or
350: ** "procedure" for a procedure within a module,
351: ** "module" for a module header (e.g., as a
352: ** separate comment block for a major module
353: ** [check .../qrymod/view.c for an example] or
354: ** in header files.
355: ** SCCS should be considered an essential tool, if only
356: ** to maintain history fields.
357: **
358: ** Deficiencies:
359: ** It should handle pseudo tty's.
360: */
361:
362: /* the following macro is defined by <sccs.h> */
363: SCCSID(%W%); /* %W% is replaced by a version number by SCCS */
364:
365:
366:
367:
368:
369:
370: # define XEQ1 5
371:
372: struct magic
373: {
374: char *name; /* name of symbol */
375: int type; /* type of symbol, defined in symbol.h */
376: int value; /* optional value. This is actually
377: * the value if it is type "integer",
378: * a pointer to the value if it is a
379: * string. */
380: };
381:
382: struct magic Stuff;
383:
384: main(argc, argv)
385: int argc;
386: char *argv[];
387: {
388: register struct magic *r;
389: register int i;
390: register int j;
391: int timebuf[2];
392: auto int status;
393:
394: /*
395: ** Note that in the declarations of argc and argv above, all
396: ** parameters to any function should be declared, even if they
397: ** are of type int (which is the default).
398: */
399:
400: r = &Stuff;
401: /* initialize random # generator */
402: time(timebuf);
403: srand(timebuf[1]);
404:
405: /* scan Stuff structure */
406: for (i = 0; i < XEQ1; i++)
407: {
408: # ifdef xTRACE
409: if (tTf(5, 13))
410: printf("switch on type %d\n", r->reltype);
411: # endif
412: switch (r->type)
413: {
414:
415: case 0:
416: case 1:
417: case 3:
418: /* initialize */
419: printf("hi\n");
420: break;
421:
422: case 2:
423: /* end of query */
424: printf("bye\n");
425: break;
426:
427: default:
428: /*
429: ** be sure to print plenty of info on an error;
430: ** "syserr("bad reltype");" would not have been
431: ** sufficient. However, don't make syserr's
432: ** overly verbose; they take much space in the
433: ** object module, and it will probably be
434: ** necessary to look at the code anyway.
435: */
436: syserr("main: bad type %d", r->type);
437:
438: }
439: }
440:
441: /* resist the temptation to say "} else {" */
442: if (i == 5)
443: {
444: i++;
445: j = 4;
446: }
447: else
448: i--;
449:
450: /* plot the results */
451: do
452: {
453: i = rand() & 017;
454: plot(i);
455: } while (j--);
456:
457: /* wait for child processes to complete */
458: wait(&status);
459: /* end of run, print termination message and exit */
460: for (i = 0; i < 2; i++)
461: printf("bye ");
462: printf("\n");
463: }
464: /*
465: ** PLOT -- Plot a Bar-Graph
466: **
467: ** Does a simple plot on a terminal -- one line's worth.
468: **
469: ** Parameters:
470: ** n (IN) -- number of asterisks to plot
471: **
472: ** Returns:
473: ** none
474: **
475: ** Side Effects:
476: ** none
477: **
478: ** Deficiencies:
479: ** Should allow scaling.
480: */
481:
482: plot(n)
483: int n;
484: {
485: register int i;
486:
487: for (i = n; i-- > 0; )
488: {
489: printf("*");
490: }
491: printf("\n");
492: }
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.