evh@vax1.acs.udel.EDU (09/27/87)
There comes a time when a programmer will have to debug some one
else's C code(or probably anyway). A professor where i used
to go to college has created some documentation standards.
I added my own opinions(etc. etc....). I am looking for
some criticism's,opinions on how you think code should
be indented(switch's, if/then brackets etc. etc.), module headers
and function headers, using your particular style/standards.
Here's a question just to start:
What purpose does the so-called k&r indenting style serve:
(personally, i dis-like it because its hell to debug).
if (x == blah) {
zip = zap;
big = deal;
}
else {
so = what;
friz = golf;
}
As opposed to:
if (x == blah)
{
zip = zap;
big = deal;
}
else
{
so = what;
friz = golf;
}
Send them to:
evh@vax1.acs.udel.eduamos@taux01.UUCP (Amos Shapir) (09/28/87)
Personally, I like the style:
if(cond) {
do_something;
} else {
do_something_else;
}
This prevents an orphan 'else' from being left on the top of the next page
of listing, making the impression that the 'if' above it has no 'else' part.
The same is valid for
while(cond) {
do_it;
}
and especially for
do {
do_it;
} while(cond);
--
Amos Shapir (My other cpu is a NS32532)
National Semiconductor (Israel)
6 Maskit st. P.O.B. 3007, Herzlia 46104, Israel Tel. +972 52 522261
amos%taux01@nsc.com (used to be amos%nsta@nsc.com) 34 48 E / 32 10 Nrsalz@bbn.com (Rich Salz) (09/29/87)
The original question asked about documentation standards, but it's really covering up for the more insidious question of whitespace and curly-brace placement. Please, let's not start another "your code is ugly and your mother dresses you funny" flame war. /r$ -- For comp.sources.unix stuff, mail to sources@uunet.uu.net. And if C is the assembly language of the 80's, why is ACP written in MIX?
mlandau@bbn.com (Matt Landau) (09/29/87)
Can we please try to head off this discussion before it's too late? Questions about programming style and standards are fine, but it's clear this conversation thread is on the verge of turning into yet another endless series of comments on why my style for indentation and whitespace is better than yours. Since this is the canonical religious issue in C programming, why don't we all just agree not to wage a Holy War :-) For those who really are concerned about coding standards, I'll point out that my project here at BBN has a set, and we try to adhere to it. It says as little as possible about indentation and whitespace beyond arguing for some consistency so that everyone's code is readable and editable by everyone else. It doesn't matter what the style is, as long as everyone agrees to stick to it. The things we really did have to specify included rules about relying on long symbol names (don't), byte or word ordering (don't, or at least provide ifdefs for all reasonable cases), or Rieser preprocessor tricks (don't), including structured comments at the beginning of source files and functions (which allow us to use trivial tools like grep to build indexes of what functions are defined in a source file, etc.), conventions for preventing multiple inclusion of .h files, and so on. If your life would be significantly enriched by seeing a copy of this document, send me mail and I'll see what I can do :-) -- Matt Landau Standard are industry's way of mlandau@bbn.com codifying obsolescence.
henry@utzoo.UUCP (Henry Spencer) (09/29/87)
> What purpose does the so-called k&r indenting style serve: > (personally, i dis-like it because its hell to debug). K&R style has precisely one major advantage: it is standard. Any C programmer can expect to have to develop some facility in reading it, especially in a source-licensed Unix installation. The same is not true of any other style. Personally, I dislike writing comments in English; Loglan or Esperanto would be much more sensible. :-) :-) However, the overriding goal is *communication*, and the fact is that my audience will understand the stuff a whole lot better if it is written in a language they are familiar with. The same thing applies to paragraphing styles. By the way, there is a pervasive myth that K&R style is hard to use. Wrong. It is hard to learn. Once learned, no problem. I thought it was hard to use and error-prone too, until our conversion to V7 required me to spend a lot of time hacking K&R-style code. Once I *really* learned it, all of a sudden it was easy to use and no more error-prone than any other (including the one I previously preferred). -- "There's a lot more to do in space | Henry Spencer @ U of Toronto Zoology than sending people to Mars." --Bova | {allegra,ihnp4,decvax,utai}!utzoo!henry
jagardner@orchid.UUCP (09/29/87)
In article <8675@utzoo.UUCP> henry@utzoo.UUCP (Henry Spencer) writes: >By the way, there is a pervasive myth that K&R style is hard to use. >Wrong. It is hard to learn. Once learned, no problem. I thought it >was hard to use and error-prone too, until our conversion to V7 required >me to spend a lot of time hacking Could somebody explain why the K&R style is so hard? I've never had any problems with it. In fact, I prefer it to just about any other style I've ever seen (except for the one Henry mentioned previously in his article). David Tanguay
jhritz@cfpas.UUCP (John Hritz) (10/02/87)
In article <9232@slate.BBN.COM> mlandau@bbn.com (Matt Landau) writes: > >The things we really did have to specify included rules about relying on long >symbol names (don't), byte or word ordering (don't, or at least provide >ifdefs for all reasonable cases), or Rieser preprocessor tricks (don't), >including structured comments at the beginning of source files and functions >(which allow us to use trivial tools like grep to build indexes of what >functions are defined in a source file, etc.), conventions for preventing >multiple inclusion of .h files, and so on. Standards that we adhere to include not relying on whether the machine does hardware or software sign extension, encouraging the writing of modularized code, keeping the scope of variables as restrictive as possible, and managing project and system wide header files with an iron fist. Sign extension becomes a problem when performing right shifts on signed operands. If your system uses software to perform this function, you will get unreliable results. The benefits of modular code have been long argued. Here we maintain that the cost of calling more functions is paid back in ease of algorythm substitution. The construction and extension of a local function library cuts down on development time. The misuse of scope in variable declarations is also a common failing in large systems. We prefer to collect all functions requiring a pathological linkage in one file and making the variable static to the file rather than making global linkages. Many of the standards adopted by our groups are discussed in detail in the book, "C Programming Guidelines" by Thomas Plum. -- UUCP: ihnp4!mibte!cfpas!jhritz (John Hritz) "Do photons have mass?... VOICE: 313-351-3404 Are any of them Catholic?"