rkl1@hound.UUCP (K.LAUX) (12/13/88)
It's not suprizing that the Indentation Standards topic has generated at lot of traffic ranging from "this is how I do it" to "I'm always gonna do it My Way". I ran into the Standards years ago working with another person. The company had a written document on Coding Standards and we were following it. Both he and I had some heated discussion on what was "better". But in the end we both stuck to the Document. The result was that the software package we were working on and which was in competition with another package finally became the company's Standard Package, because our package was Consistent throughout and the other was obviously Kludged together. The point here is that Personal Preferences just don't count (you can always agree to disagree), and that following a Standards Document does count. Whenever 2 or more people are working on a project, Some Form of Standards should be adhered to. This gets everyone 'talking' on the same level. There just isn't time for someone to spend trying to adjust to multiple styles. I liken it to people's handwriting (in script) - everyone's different. That's why typefaces were invented - to standardize handwriting. So, if you don't have a Coding Standards document to spell things out, create one and get it approved. I never said it was *required* for everyone to like/agree with it - just to follow it. --rkl
rob@pbhyf.PacBell.COM (Rob Bernardo) (12/13/88)
In article <2802@hound.UUCP> rkl1@hound.UUCP (K.LAUX) writes:
+ The point here is that Personal Preferences just don't count (you can
+always agree to disagree), and that following a Standards Document does count.
+Whenever 2 or more people are working on a project, Some Form of Standards
+should be adhered to. This gets everyone 'talking' on the same level. There
+just isn't time for someone to spend trying to adjust to multiple styles.
In my office, coding standards are to be adhered by regardless of the number
of the people *currently* working on the project, because it's highly likely
someone else will be working on the project at a later date, if even just
to provide bug fixes for it.
--
Rob Bernardo, Pacific Bell UNIX/C Reusable Code Library
Email: ...![backbone]!pacbell!pbhyf!rob OR rob@pbhyf.PacBell.COM
Office: (415) 823-2417 Room 4E750A, San Ramon Valley Administrative Center
Residence: (415) 827-4301 R Bar JB, Concord, Californiaevan@plx.UUCP (Evan Bigall) (12/14/88)
All this talk of coding standards has reminded me of and idea for a program
I was almost involved in writing....
Once upon a time I was taking a class on software engineering, and we were
thinking of ideas for a fairly substantial semester project for five. One
of the ideas tossed around (I think original credit goes to Dan Nachbar)
was to write a P'er. It would consist of two parts, the first part would
take as input a grammar for the language, and a substantial (yes substantial
is a very nebulous term) amount of code in the style of the user. The output
would be a data file describing the relationships between the different
grammatical constructs. The second part (by far the easier) would take as
input the data file and some code not in the style of the user. The program
would then pee on the code, ie: convert it to the users style.
Sounds like a great idea? Unfortunatly as we tried to solidify the idea we
ran into a mess of problems, (what to do about inconsistencies and
incompleteness in the users sample....). I was never conviced that the
idea was completely unworkable, but because the emphasis of the class was on
the execution of a large but fairly straightforward project and not on
producing the coolest pice of software possible we tossed the idea. Its one
of those things that has been at the back of my mind for a long time. Any
one care to comment on the feasability or maybe even take up the banner?
Evan
-----
Evan J Bigall (408)943-2283
{most backbones}!sun!plx!evan
I barely have the authority to speak for myself, certainly not anybody else.nelson@sun.soe.clarkson.edu (Russ Nelson) (12/14/88)
In article <2802@hound.UUCP> rkl1@hound.UUCP (K.LAUX) writes:
So, if you don't have a Coding Standards document to spell
things out, create one and get it approved. I never said it was
*required* for everyone to like/agree with it - just to follow it.
I am the poster who started the whole ball of was [rolling | melting] again.
I got quite a few responses both by mail and by follow-ups to my
query, in which I asked if there exist any standards for indentation.
Several people pointed out that K&R use a consistent indentation in
their books, and also that cb and indent will impose a consistent
indentation. Curiously, I didn't hear that people actually *use* K&R
or cb formatting.
The general advice that I got was to, when modifying existing code,
stick to the existing style, and when creating new code, use a
consistent style.
I also realize that the question that I meant to ask was larger than
just indentation -- it also covers comment style, whitespace, brace
positioning, etc. So, to come to my rescue (?) is an article by Ken
Arnold his C Advisor column in Unix Review Vol. 6 No. 12 on "Stylistic
Stuff".
I was hoping to find out that there are only a few styles in use, so
that a user could become familiar with them all and use whichever was
appropriate (as above).
--
--russ (nelson@clutx [.bitnet | .clarkson.edu])
To surrender is to remain in the hands of barbarians for the rest of my life.
To fight is to leave my bones exposed in the desert waste.djones@megatest.UUCP (Dave Jones) (12/14/88)
From article <NELSON.88Dec13135433@sun.soe.clarkson.edu>, by nelson@sun.soe.clarkson.edu (Russ Nelson): ... > I got quite a few responses both by mail and by follow-ups to my > query, in which I asked if there exist any standards for indentation. > Several people pointed out that K&R use a consistent indentation in > their books, and also that cb and indent will impose a consistent > indentation. Curiously, I didn't hear that people actually *use* K&R > or cb formatting. > I use a public-domain emacs "mode", just because it is convenient. Occasionally I use "indent". > The general advice that I got was to, when modifying existing code, > stick to the existing style, and when creating new code, use a > consistent style. > Another alternative is to change the style of existing code by running it through a pretty printer. (If the author is still around and views code as art, consider the political consequences before you reformat it.) > I also realize that the question that I meant to ask was larger than > just indentation -- it also covers comment style, whitespace, brace > positioning, etc. So, to come to my rescue (?) is an article by Ken > Arnold his C Advisor column in Unix Review Vol. 6 No. 12 on "Stylistic > Stuff". > I have that article in front of me. It contains some good stuff. But one of the examples in the article would not be acceptable to me as production code. I'm not calling the author to task. The example in question is only billed as illustrating comment usage, and I have no disagreement on that subject. It's the names of the variables and the manner in which they are declared that I would change. For one thing, I virtually always give variables descriptive names which can be spoken over the telephone. I don't leave out vowels. I spell everything out, except for standard abbreviations, such as "init". Only if the scope of a variable is extremely restricted and the purpose of the variable very obvious, will I use a name such as "i" or "j". Even then, I am likely to feel a twinge of regret and change the "i" to "index" or something. I also am very meticulous about restricting the scope of variables. Rather than having "reusable" global variables which function differently in different parts of the program, I declare them in a block which is active only so long as the variable is live: if (bye_required) { int byes_printed; for ( byes_printed = 0; byes_printed < 2; byes_printed++) printf("bye"); } I attempt to declare the variable as close as possible to the first place were it takes on a meaningful value. Notice that I don't always declare constant integers other than 0 and 1 with #defines. I #define a constant only if the definition has abstraction value: for example, if the constant appears in more than one place or might appear in more than one place in a future version, and is subject to change in future versions. Documentation value is not enough. If the constant is only used in one place, then an inline comment can justify its existence, and will not send the reader grepping through .h files to discover what the value _really_ is. I also try to use a very consistent style in data and procedure definitions. Structure-types are always capitalized. Routines that deal pricipally with one kind of structure are named for the structure, and the first paramenter is always a pointer to the structure, and is always named "obj". There is always an initializer routine, a "new" routine, and when appropriate, a "cleanup" routine which frees memory before a structure is discarded. List* List_init(obj) register List* obj; { obj->first = (List_element*)0; obj->last = (List_element*)0; obj->count = 0; return obj; } List* List_new() { return List_init(New(List)); } Style can largely be viewed as being nice to prospective readers. I restrict the scope of variables so that the reader need not "solve theorems" to determine when values are live, and will not have to search here and there in order to verify the effective scope of the variable. I avoid trival #defines in order to relieve the reader of the necessity of grepping around in .h files. If the reader is likely to have a high-resolution monitor, I line up the curly braces -- close brace under open brace -- to make it easier to pair up the related ones. If the reader is likely to be using an old terminal, or the code is to be printed in book format, I use the K&R style to save vertical space.
pokey@well.UUCP (Jef Poskanzer) (12/14/88)
In the referenced message, nelson@clutx.clarkson.edu wrote: >The general advice that I got was to, when modifying existing code, >stick to the existing style, and when creating new code, use a >consistent style. Yes, I agree with that. But I have to add one more: when modifying existing code that does not consistently use any one style, it's a judgement call. If you think you can figure out what style was intended, it may be easier to modify the code to conform to that; otherwise, you have no choice but to modify the code to conform to your own consistent style. I get a lot of code sent to me for inclusion in the Portable Bitmap package. In almost every case, I end up modifying it to conform to my own style. This is *good* code, I almost never find bugs in the stuff I get, but the indentation and punctuation usually remind me of when I used to see how drunk I could get and still write BASIC. A lot of good programmers think they have better things to do than get the indentation consistent. They are wrong, but in my case I can't be choosy. --- Jef Jef Poskanzer jef@rtsg.ee.lbl.gov ...well!pokey Fools rush in and get the best seats.
chip@tct.uucp (Chip Salzenberg) (11/29/90)
According to rmartin@clear.com (Bob Martin): >At Clear we have instituted a style standard which [...] >demands that comments always be placed on closing braces. >[...] >The convention is "demanded" because it is cheap, easy, has very >few down-sides, and the _possibility_ of significant up-sides. I'd say that the down side of this rule includes two problems which are (to me) very significant: such comments clutter the code and they make commentary a very low-level syntactical entity. In my opinion, mandatory comments on *syntactic* grounds are likely to lead to worse-than-nothing garbage like "++x; /* add one to x */" as programmers fill in just anything to comply with the standard. -- Chip Salzenberg at Teltronics/TCT <chip@tct.uucp>, <uunet!pdn!tct!chip> "I've been cranky ever since my comp.unix.wizards was removed by that evil Chip Salzenberg." -- John F. Haugh II
rmartin@clear.com (Bob Martin) (12/01/90)
In article <2753F21B.2F6@tct.uucp> chip@tct.uucp (Chip Salzenberg) writes: >According to rmartin@clear.com (Bob Martin): >>At Clear we have instituted a style standard which [...] >>demands that comments always be placed on closing braces. > >In my opinion, mandatory comments on *syntactic* grounds are likely to >lead to worse-than-nothing garbage like "++x; /* add one to x */" as >programmers fill in just anything to comply with the standard. This is a real risk, but it is seldom the case that a reasonable identifier cannot be tacked onto a closing brace. The alternative of not demanding the comments on closing braces exposes you to the danger of a function that has grown to span (god forbid) multiple pages and has no comments telling you where the braces line up. Again the cost is negligible, the risk is low, and the benefit is significant. -- +-Robert C. Martin-----+:RRR:::CCC:M:::::M:| Nobody is responsible for | | rmartin@clear.com |:R::R:C::::M:M:M:M:| my words but me. I want | | uunet!clrcom!rmartin |:RRR::C::::M::M::M:| all the credit, and all | +----------------------+:R::R::CCC:M:::::M:| the blame. So there. |
scs@adam.mit.edu (Steve Summit) (12/08/90)
In article <1990Nov30.180913.20890@clear.com> rmartin@clear.com (Bob Martin) writes: >...it is seldom the case that a reasonable >identifier cannot be tacked onto a closing brace. >The alternative of not demanding the comments on closing braces >exposes you to the danger of a function that has grown to span >(god forbid) multiple pages and has no comments telling you where >the braces line up. Not to argue with you, but just to present an opposing viewpoint, I've always felt that "} /* end if */" and the like make code look like it was written by amateurs who are still shaky on mere syntactic details. Good programmer's editors have "show matching brace" commands which work well in those cases when the code layout doesn't make brace matching obvious (or, as you point out, when long blocks span pages or screens). I suppose a comment would help when you've got } } } /* some cleanup code here */ } } } and it's important to know which block(s) have just been exited and which block(s) the cleanup code is still in. However, rule-based /* end if */'s and /* end for */'s would in this case only be a partial solution, since they would require the reader to search back to find the opening if or for to discover the purpose of the blocks being left (resp. blocks still in). This search would require a brace-matching editor, or careful tab counting, if there were several if's and for's in the blocks being searched. Comments like /* end of ^C special case */ or /* end of argument parsing loop */ could be useful. Perhaps that is what your standard requires. I should think, though, that comments like these (as opposed to their less-useful brethren /* end for */ and /* end if */) would be better requested with a rule like "code shall have useful comments" (perhaps with hints like "...such as at the beginning (and end) of complicated blocks") than by simply declaring that "all closing braces shall have comments." (Again, perhaps your standard does say something like the former; I haven't seen it. It is admitted, too, that rules like the latter are, while less useful, much easier to enforce.) Steve Summit scs@adam.mit.edu
gwyn@smoke.brl.mil (Doug Gwyn) (12/08/90)
In article <1990Dec7.163617.10916@athena.mit.edu> scs@adam.mit.edu writes: >Good programmer's editors have "show matching brace" commands >which work well in those cases when the code layout doesn't make >brace matching obvious (or, as you point out, when long blocks >span pages or screens). I align { and } vertically so that I can immediately find the matching brace visually. It is also worthwhile to attempt to keep the code simple enough that compound statements don't span too many lines; this is not always feasible, but it's a worthwhile coding goal. >Comments like /* end of ^C special case */ or /* end of argument >parsing loop */ could be useful. Perhaps that is what your >standard requires. I should think, though, that comments like >these (as opposed to their less-useful brethren /* end for */ and >/* end if */) would be better requested with a rule like "code >shall have useful comments" (perhaps with hints like "...such as >at the beginning (and end) of complicated blocks") than by simply >declaring that "all closing braces shall have comments." I agree with the general sentiments that Steve expressed. Comments should serve a purpose. What purpose? To help a subsequent code reader understand the code. A functional specification for this requirement is recommended, rather than an attempt to achieve the goal without mentioning it but rather simply specifying a bunch of syntactic rules that relate only indirectly to the real goal. One should learn this from observing the mistakes of legislators.
chris@mimsy.umd.edu (Chris Torek) (12/08/90)
In article <1990Dec7.163617.10916@athena.mit.edu> scs@adam.mit.edu (Steve Summit) writes: >Not to argue with you, but just to present an opposing >viewpoint, I've always felt that "} /* end if */" and the like >make code look like it was written by amateurs who are still >shaky on mere syntactic details. I dunno, this sounds like argument to me :-) . Seriously, though, I agree; I have been known to delete all such comments from some bit of source before working on it: >Comments like /* end of ^C special case */ or /* end of argument >parsing loop */ could be useful. I much prefer what might be called `conversational' comments, as in: /* * Read giffgaff from the user until the fire alarm goes off * or we run out of sand grains, whichever comes first. */ . . . } } /* * All of the sand grains were taken care of * above, so the only thing we have to worry * about here is the fire alarm. */ . . . -- In-Real-Life: Chris Torek, Univ of MD Comp Sci Dept (+1 301 454 7163) Domain: chris@cs.umd.edu Path: uunet!mimsy!chris
gordon@osiris.cso.uiuc.edu (John Gordon) (12/08/90)
gwyn@smoke.brl.mil (Doug Gwyn) writes: >I agree with the general sentiments that Steve expressed. Comments >should serve a purpose. What purpose? To help a subsequent code >reader understand the code. A functional specification for this Or to help *you* understand it, 6 months later... :-)
ea08+@andrew.cmu.edu (Eric A. Anderson) (12/09/90)
>From: rmartin@clear.com (Bob Martin) >The alternative of not demanding the comments on closing braces >exposes you to the danger of a function that has grown to span >(god forbid) multiple pages and has no comments telling you where >the braces line up. This is why you can run programs like gnu-emacs which will auto format your code for you, and tell you if things don't match up. But I happen to be of the theory that a function should never be longer than a screen, there is seldom any point, and breaking it up allows some amount of reusability. -Eric ********************************************************* "My life is full of additional complications spinning around until it makes my head snap off." -Unc. Known. "You are very smart, now shut up." -In "The Princess Bride" *********************************************************