Relay-Version: version B 2.10 5/3/83; site utzoo.UUCP Path: utzoo!utgpu!water!watmath!clyde!rutgers!husc6!cmcl2!brl-adm!adm!tom@vax1.acs.udel.EDU From: tom@vax1.acs.udel.EDU Newsgroups: comp.lang.c Subject: Re: documentation standards........ Message-ID: <9897@brl-adm.ARPA> Date: Thu, 22-Oct-87 09:12:59 EDT Article-I.D.: brl-adm.9897 Posted: Thu Oct 22 09:12:59 1987 Date-Received: Sat, 24-Oct-87 20:21:49 EDT Sender: news@brl-adm.ARPA Lines: 126 From: SAVILLE Subject: documentation standards........ > Here are some standards developed at the univ. of del. for C code, > and program design/'style'. I don't agree with everything here > (as some of you probably don't either). This standard was actually for general programming; this is the 'C' version. there is also a nearly identical 'Pascal' standard around here. This standard is not well suited to the way *I think* C code should be written and documented. Nor, I might add, is it an accepted standard around here. Dr. Amer (the author) insists upon it in all of his classes, as do a few instructors who learned C from him, but most code is written/doc'ed according to no particular standard. I think that coding standards standards are a good thing as long as they are well adapted to the language, and not too restrictive. ie. i'm much more likely to accept a set of guidelines than a 15+ page formal specification of how every facet of a program WILL be done. We have a number of "AmerDoc" programs, scripts, emacs-fns etc. written by people who over the years decided that they were not going to deal with some of the more insidious busy-work aspects of this standard. For example: > Comments serve two main purposes: > [...] > > 3. Input Parameters: names and descriptions of parameters passed > to the procedure > 4. Returned Values: for a procedure, names and descriptions of > affected parameters; for a function, in addition, an explana- > tion of the single returned value > 5. Procedures/Functions Called: names of procedures and functions > that are called from the module (with optional descriptions). > System utilities such as printf, getchar need not be document- > ed > 6. Procedures/Functions Calling: names of procedures and func- > tions that call this module > 7. Local Variables: names and descriptions of every local vari- > able > 8. Global Variables Used (and how modified): names of all global > variables used and how the module modifies them > 9. Global Constants: names and description of globals [This sec- > tion would be found in the main program only.] None of this is needed in a header comment for a function. It can be produced on demand if it is ever desired by any half decent cross reference program. Data structures, vars and things should of course be adequately documented where they are declared and used. Some of these items, esp. #6 are impossible to satisfy for any general purpose code. Imagine trying to write some library fn, say 'printf()' to conform to this standard. After all, isn't the one of the goals of a standard to encourage modularity and generality rather than coding many things over and over since their design was too problem-specific. I agree with most of the other guidelines about documenting as long as nothing but purpose/description, author, history & known bugs goes in a header comment. if one wants to excessively comment a piece of C code why not create a foo.readme file rather than making it hard to find the code in foo.c Here are some other improvements I would suggest for this standard: 1. Delete section on indenting code. Almost everyone who has written more than 10 programs has their own indentation style that they think is better than anyone elses. As long as it is consistent and readable it doesn't really matter. Any group working on the same project should indent the same way. If you don't like the way someone indents you can always feed their code to a pretty printer before you look at it. Besides his indentation style looks ugly :-) 2. This section on initialization is NOT for C and is not a good idea for any language which allows compile time initialization. > Except for static local variables, put all initialization statements > in a procedure entitled "initialize" and call it at the beginning of > the main program. This is a foolish thing to do since all externals and statics can be initialized "for free" to nearly anything desired at compile time, (cf. constant expressions) but an 'initialize()' proc would generate code and take time to execute. Automatic variables could of course be handled that way but it seems clearer (and less expensive) to me to assign them values right where they are declared. Alter the above lines to read: "Group all initialization statements together into one clearly labelled place. For externals this should be either the beginning of the main program file or a file with a name like "init.c". For locals this should be the beginning of the block where they are declared." 3. Include more guidelines on using: types scope of variables (there are 3 types: global, file, and block) cpp & header files. Only preprocesser directives, and declarations (not definitions) should appear in ".h" files. Never executable code. Fully parenthasize all #define constants and macro's. If you say #define FOO sizeof(int) + sizeof(char) Someone will inevitably say "4 * FOO" and then hate you because they got 17 as the value instead of 20. file and/or module organization in general. (his example leads one to believe that programs should be one monolithic file) I prefer a separate file for every function unless you have several that clearly belong together in one "module" (see K&R p.77 and section 4.6 for the classic stack module example). This gives you the maximum benefit from 'make' and lets even dumb linkers produce the smallest binarys possible. If you have `make' you should take advantage of it, and if you don't have make you should get it. At times the 1 fn per file approach may seem a bit extreme but it certainly encourages modularity. 4. Get a real example. The current one is a thinly disguised pascal program. tom