ast@cs.vu.nl (Andy Tanenbaum) (12/26/88)
Many people have asked me for the MINIX "style" message that I posted some
time ago. Here is a copy of it.
Andy Tanenbaum (ast@cs.vu.nl)
We haven't had a good religious war since the discussion about the PDP-11
memory management unit. Let's give this a try. There was a recent posting
of cb (C beautifier). I am not going to use it because it does not beautify.
It uglifies, and cu is already taken. The MINIX kernel, FS, and MM are all
below. If anyone feels like writing a cb that makes all program adhere to the
book style, that would be great. Other cbs need not apply. For more details,
look in the book. There are 250 pages of examples there.
SAMPLE FUNCTION
struct inode *get_inode(dev, numb)
dev_nr dev; /* device on which inode resides */
inode_nr numb; /* inode number */
{
/* Find a slot in the inode table, load the specified inode into it, and
* return a pointer to the slot. If 'dev' == NO_DEV, just return a free slot.
*/
register struct inode *rip, *xp;
int k, mark;
/* Search the inode table both for (dev, numb) and a free slot. */
xp = NIL_INODE;
if (rip->i_dev == dev && rip->i_num == numb) {
/* This is the inode that we are looking for. */
rip->i_count++;
return(rip); /* (dev, numb) found */
} else {
xp++;
count++;
if (count > N) limit = 1;
}
for (rip = &inode[0]; rip < inode[MAX]; rip++) {
if (rip->i_num == 0) {
mark = 1;
k = rip - inode;
}
}
}
1. Function types (e.g., struct inode *) are written on the same line as the
function name.
2. No spaces before or after parentheses in functions or calls.
3. One space after commas in argument lists.
4. Each is described by a short comment starting at tab stop 4 (col 33).
5. Open curly brace is on a separate line following the argument list;
6. Each function starts with a comment in the form of one or more complete
sentences. Multiline comments all contain vertically aligned asterisks.
7. Include a blank line after the initial comment.
8. All declarations come next. No inner declarations, e.g. {int x; ...}.
9. A blank line after the last declaration.
10. Initial indentation is two spaces. Subsequent indentation is at tab stops.
This reduces the chance of exceeding 80 characters on a line.
11. Function bodies are divided into logical sections. Each section begins
with a capitalized full sentence. Sections are separated by blank lines.
12. Short if statements are included on a single line.
13. Long if statements contain the { on the first line. The closing } is
aligned with the if. If both the then and else parts are multistatement,
the } else { is on one line and aligned with the if.
14. Use { } to enclose any complex statement, even if not required, as in
the for statement above.
15. Where useful, include short comments at the end of statements. These
comments are not whole sentences and do not begin with capital letters.
They start at tab stop 4 (col 33) where possible. They should fit on
the line and never run beyond column 80.
16. In general, leave a space around operators like +, ==, < etc.
17. Use parentheses to enclose arguments in return statements.
Andy Tanenbaum (ast@cs.vu.nl)eric@cs2.wsu.edu (12/28/88)
Andy Tanenbaum <ast@cs.vu.nl> write: > 1. Function types (e.g., struct inode *) are written on the same line as the > function name. The reason for putting the function name on its own line is that you can then do "/^<function_name>" in an editor like vi to find the definition of a function. It is much more difficult to have to remember the type the function returns (and also how it was spaced). Of course, tags are used for this, but sometimes it's just easier to do a search. > 2. No spaces before or after parentheses in functions or calls. This (and many below) are quite difficult for a beautifier without doing a fairly complete parse of the input source. The purpose of 'cb' as I understand it is not to do such a parse, but rather to adjust mostly indentation. > 4. Each is described by a short comment starting at tab stop 4 (col 33). > 6. Each function starts with a comment in the form of one or more complete > sentences. Multiline comments all contain vertically aligned asterisks. > 7. Include a blank line after the initial comment. I don't feel that commenting style has any place in a C beautifier. > 8. All declarations come next. No inner declarations, e.g. {int x; ...}. Are you implying that a particular style of programming should preclude the use of the full language? > 10. Initial indentation is two spaces. Subsequent indentation is at tab stops. > This reduces the chance of exceeding 80 characters on a line. Any C beautifier which is worth anything will make the number of spaces to indent blocks a parameter. > 12. Short if statements are included on a single line. Short? How Short? Well, it looks to me like Andy is making a case more for programming style than program code format. Despite what may look like critical comments up above, I generally approve of the format used throughout the MINIX code. Unfortunately, not everybody is going to. In a real commercial environment where we were all getting paid by Andy to play with MINIX, it would be quite reasonable to impose such restrictions (guidelines) on code format. But, MINIX is not a commercial product (though it is copyrighted) and many of us work on MINIX just for the joy it gives to get a program to do what you want. For the MINIX code itself, it is reasonable to maintain a rigid format across all functions and files. This makes the code easier to follow. However, it is becoming obvious that there is much more to MINIX than the code for the OS itself. For the code which people contribute, it is ridiculous to require a particular format. I would like to see any attempts at a C beautifier. I think that the ones which will be most useful will be those that are the most flexible. How about a table driven systems similar to 'termcap' or 'printcap' or 'vgrindefs' which allows each person to tailer the output to there own taste? Of course, mine is not the only opinion, but I don't think it is right for a C beautifier to be moving comments or code to any significant degree. Perhaps some kind soul out there will volunteer to write a nice, flexible beautifier which is written primarily in YACC and LEX (bison and flex) that can easily be modified to particular tastes. Eric Schneider (eric@wsu.edu)