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.