[comp.software-eng] Style rules for C shops

friedl@vsi.UUCP (Stephen J. Friedl) (04/13/88)

Hi net.people,

      I am interested in knowing how various C shops implement
company-wide style guidelines.  It strikes me that it would be
madness to allow everybody to have their own style, as they can
be *so* different that it would be difficult for others with a
radically different style to maintain down the road.  On the
other hand, it seems like a morale-breaker to have absolute
strict rules that leave no room for personal style.  Somewhere
in the middle is the right approach that balances the programmer's
individuality with the need for corporate consistency.

     This question is more a management one than a technical one
-- I already have the style rules, I just don't know how
rigorously it should be mandated.

     I would appreciate getting Email from those who have some
thoughts on this.

     Thanks,
     Steve
-- 
Steve Friedl   V-Systems, Inc.   "Yes, I'm jeff@unh's brother"
friedl@vsi.com  {backbones}!vsi.com!friedl  attmail!vsi!friedl

daveb@geac.UUCP (David Collier-Brown) (04/14/88)

In article <528@vsi.UUCP> friedl@vsi.UUCP (Stephen J. Friedl) writes:
>Hi net.people,
>
>      I am interested in knowing how various C shops implement
>company-wide style guidelines.  It strikes me that it would be
>madness to allow everybody to have their own style, as they can
>be *so* different that it would be difficult for others with a
>radically different style to maintain down the road.  On the
>other hand, it seems like a morale-breaker to have absolute
>strict rules that leave no room for personal style.

  Try invalidating the question (ie, don't make it a choice at all!)

	1) Lay down functioning-of-program standards.
	2) Make anything changed by pretty-printers optional.
	   2.1) Provide "indent", "cb" and "promote/demote"
		available for transforming "mere" style form one
		to another.
-- 
 David Collier-Brown.                 {mnetor yunexus utgpu}!geac!daveb
 Geac Computers International Inc.,   |  Computer Science loses its
 350 Steelcase Road,Markham, Ontario, |  memory (if not its mind) 
 CANADA, L3R 1B3 (416) 475-0525 x3279 |  every 6 months.

news@santra.UUCP (news) (04/20/88)

In article <528@vsi.UUCP> friedl@vsi.UUCP (Stephen J. Friedl) writes:
>      I am interested in knowing how various C shops implement
>company-wide style guidelines.  It strikes me that it would be
>madness to allow everybody to have their own style, as they can
>be *so* different that it would be difficult for others with a
>radically different style to maintain down the road. 
>... I already have the style rules, I just don't know how
>rigorously it should be mandated.

I have had to think about this issue for a company that practices 
programming-in-the-large (over 2 million lines of hll source code) with
the software having a long lifetime (>= 10 years). In an environment 
like this, where the readability (hence maintainability) of programs is
of paramount importance, I would not hesitate to promote style rules 
if I was convinced that they improve readability. The question, though, is
how do you enforce these rules, i.e., make sure that everyone is using
them. One solution is to write a program that does style checking according
to your rules and refuses to pass a program to the compiler if the style
used is significantly below the advocated standard. That would, as you
rightly say, penalise individuality and be too demanding on the computer
resources if the checker was run each time a compilation was wanted.
For these reasons, I would rather go for a style analyser that would be 
invoked only once before the software is frozen for release in the
database. Large deviations from the standard would have to report to
management before being allowed to proceed with freezing the software.
This way we can deal with "intelligent" deviations.

mouse@mcgill-vision.UUCP (der Mouse) (04/23/88)

In article <528@vsi.UUCP>, friedl@vsi.UUCP (Stephen J. Friedl) writes:
> I am interested in knowing how various C shops implement company-wide
> style guidelines.  It strikes me that it would be madness to allow
> everybody to have their own style, as they can be *so* different that
> it would be difficult for others with a radically different style to
> maintain down the road.  On the other hand, it seems like a
> morale-breaker to have absolute strict rules that leave no room for
> personal style.

As someone else said, anything that a program can change should not be
specified.  In effect, each worker should have a "make this conform to
my idea of nice code" program, and anything that's changed by such
programs should not be required of anyone (es.g.: a tab or four spaces
indent per level, spacing around parens in function calls, spacing
around operators in expressions...).  Then require good documentation
of each module's interface: input arguments and where they're found,
output arguments and where they're found, what happens when the
arguments overlap (:-), what errors can occur and how they're handed
back to the caller, etc....

But also, these personalized pretty-printers shouldn't get much use,
because the only case where one person should work on another person's
code is when the responsibility for that piece of code changes hands as
well.  (The "too many cooks" argument - with software, as with *most*
other things, I believe that "too many" means "more than one".)  The
project should be split up sufficiently that any given routine is the
province of exactly one programmer.  If you have two or more people
working on some piece of code, it's time to subdivide it and parcel the
pieces out.

Of course, that's just my opinion.

					der Mouse

			uucp: mouse@mcgill-vision.uucp
			arpa: mouse@larry.mcrcim.mcgill.edu

rion@wdl1.UUCP (Rion Cassidy) (04/26/88)

news@santra.UUCP (news) writes:

>In article <528@vsi.UUCP> friedl@vsi.UUCP (Stephen J. Friedl) writes:
>>      I am interested in knowing how various C shops implement
>>company-wide style guidelines.  It strikes me that it would be
>>madness to allow everybody to have their own style, as they can
>>be *so* different that it would be difficult for others with a
>>radically different style to maintain down the road. 
>>... I already have the style rules, I just don't know how
>>rigorously it should be mandated.
>
>I have had to think about this issue for a company that practices 
>programming-in-the-large (over 2 million lines of hll source code) with
>the software having a long lifetime (>= 10 years). In an environment 
>like this, where the readability (hence maintainability) of programs is
>of paramount importance, I would not hesitate to promote style rules 
>if I was convinced that they improve readability. The question, though, is
>how do you enforce these rules, i.e., make sure that everyone is using
>them.

I can't claim a great deal of experience in this vien, but it seems to
me that if you're producing that much code that has to be maintained
for that long of a period, you should be doing code reviews,
walkthroughs, or inspections as part of the implementation process
simply to assure the correct functionality.  It would be easy to
additionally check for programming style at the same time; make it
clear to the programmers that this will happen and that their
promotions/raises can be effected if they haven't followed the style
'rules', which brings me to a second point.

The suggestion of having some kind of parser or compiler to check for
programmers following style rules would obviously be too confining and
probably counterproductive to an extent.  I would advocate style
'guidelines'; suggestions for programming style indicating suggested
maximum number of lines per file, function, where comments are needed,
length of variable names, etc. This could be checked when doing the
inspections mentioned above.  This introduces a degree of
subjectivity, but I feel it is preferable to the totally objective,
automated approach discussed.

Rion Cassidy							
Ford Aerospace
rion@ford-wdl1.arpa
...{sgi,sun,ucbvax}!wdl1!rion

Disclaimer: My employer forced me to write this at gun-point.
I assume no responsibility whatsoever for what I've said here.

bobd@opus.UUCP (Bob Donaldson) (04/27/88)

In article <1066@mcgill-vision.UUCP>, mouse@mcgill-vision.UUCP (der Mouse) writes:
> /*	many lines of commentary on C style enforcers	*/
>
> But also, these personalized pretty-printers shouldn't get much use,
> because the only case where one person should work on another person's
> code is when the responsibility for that piece of code changes hands as
> well.  (The "too many cooks" argument - with software, as with *most*
> other things, I believe that "too many" means "more than one".)  The
> project should be split up sufficiently that any given routine is the
> province of exactly one programmer.  If you have two or more people
> working on some piece of code, it's time to subdivide it and parcel the
> pieces out.
> 
This misses the point - the idea behind consistent style is to reduce
the life-cycle cost of software.  This includes not only the current
development task, but also subsequent maintenance tasks, enhancement
projects and (last but not least) software reuse.  Unless we intend
to be chained to any software we write forEVER we better learn to live
with style guidelines that lower these costs for our employers.

----------------------------------------------------------------
Bob Donaldson              ...!ut-emx!juniper!radian!bobd
Radian Corporation
PO Box 201088              (512) 454-4797
Austin, TX  78703

Views expressed are my own, not necessarily those of my employer.

jefu@pawl19.pawl.rpi.edu (Jeffrey Putnam) (04/27/88)

In article <3850009@wdl1.UUCP> rion@wdl1.UUCP (Rion Cassidy) writes:
>news@santra.UUCP (news) writes:
>>In article <528@vsi.UUCP> friedl@vsi.UUCP (Stephen J. Friedl) writes:

   (edited in the interests of brevity - i hope that i did not change
    the substance of any of the comments)

>>>      I am interested in knowing how various C shops implement
>>>company-wide style guidelines.  It strikes me that it would be
>>>madness to allow everybody to have their own style, as they can
>>>be *so* different that it would be difficult for others with a
>>>radically different style to maintain down the road. 

I have found that it is less important to force everyone into using
a single style than to get them to use their personal style consistently.
The only major exception to this is in naming visible objects (variables,
functions).  The important thing seems to be internal consistency, not
global consistency - but see below.

>>			... I would not hesitate to promote style rules 
>>if I was convinced that they improve readability. The question, though, is
>>how do you enforce these rules, i.e., make sure that everyone is using
>>them.

>				         	... make it
>clear to the programmers that this will happen and that their
>promotions/raises can be effected if they haven't followed the style
>'rules'...

Whee!  (again, see below)

>					...  I would advocate style
>'guidelines'; suggestions for programming style indicating suggested
>maximum number of lines per file, function, where comments are needed,
>length of variable names, etc. This could be checked when doing the
>inspections mentioned above.  This introduces a degree of
>subjectivity, but I feel it is preferable to the totally objective,
>automated approach discussed.

Sounds fairly flexible.  Good.  

All this seems to me to be ignoring the state of the art in software
and hardware.  It does not seem impossible to construct a program
construction tool that would allow each programmer to build a program
in whatever style seems appropriate to her, (with the possible
exception again of globally visible objects) and would be able to
present the same code (even at the same time) to another user with
another style (an example-based formatting system and a smart
displayer).  Even local variable names could be mapped if desired
(that is, it is easy enough to see how to map "HelloThere" into
"hello_there", or even, given enough power in the tool, into "Hello There!"
(since lexical analysis is only really needed in parsing streams of
raw characters)).  Comments could be put in boxes or different fonts,
the scope of loops could be indicated with vertical bars - or boxes,
rather than using indentation.  Compiler directives could be hidden or
eliminated (Im thinking of some of my C programs that end up with
_lots_ of preprocessor lines, and i would like (optionally) to not
even see them, only the text that is actually generated).  And so
on.

I dont know of anyone who has actually built such a system, but do
not believe it is very far in the future.  Further, though it wont
solve even a major part of software engineering problems, it should
enable us to stop worrying about things like style rules.


jeff putnam  
jefu@pawl.rpi.edu -or- jeff_putnam%rpitsmts@itsgw.rpi.edu
"People would rather believe a simple lie than the complex truth."

decot@hpisod2.HP.COM (Dave Decot) (04/29/88)

> Unless we intend
> to be chained to any software we write forEVER we better learn to live
> with style guidelines that lower these costs for our employers.

I have always thought that insisting that the author support his own
software forEVER would lead to much better programming practices and
higher maintainability...  :-)

winter@hpldola.HP.COM (Kirt Winter) (05/05/88)

In my just completed MS work at Oregon State, I looked into the possibility of
doing a truly flexible prettyprinter.  I'll summarize some of the things I
learned.

In particular, I chose to look at syntactic style (where should this keyword/
construct be placed relative to anoter).  Once you decide that flexibility is
necessary, the next question is how one goes about specifying his/her style
to the prettyprinter.

In the prototype I constructed (works with standard Pascal and Turbo 3.0
dialect) you give it a "style sample".  This can either be done by modifying
a sample program that I provided (or giving a different sample program that
you have already written), giving that sample to the prettyprinter, and use a
command-line option that tells the prettyprinter to "learn".

The prototype (while not bug free) does a nice job of capturing the vast
majority of syntactic styles given to it.  It could easily be modified to
capture more (at least by me, it's a little "hackish" right now).

I do plan (sometime, I just started a new job) to do a C version sometime
in the future.  I guess if there is sufficient interest/market, I might get
around to it sooner.  I have also been told of a flexible prettyprinter for
the Logitech Modula II compiler (I think it is now included with it).

What it doesn't do is do any modification of keywords, identifiers, etc.  If
this is a big requirement, it is easy to add, it just didn't fall in line
with my MS work, and I had a job waiting so...

We've thought about several possible uses for it, and I'll just list a few
of them here:

	- Would allow for "company standards" as well as individual taste.
	  (you could change company style to your style to someone else's
	  and back)

	- Use the produced "style files" (in the learn phase) to measure
	  deviation from standards.

	- In the academic world, use "style files" to identify authorship.
	  (studies have shown that current metrics, including Barry &
	  Meekings style measure, aren't useful for this task)

	- Use it as a research tool to decide what (if anything) in syntactic
	  style makes a style "good" for comprehension, or how one's style
	  evolves over time (and perhaps how much that correlates with a
	  person's proficiency with a particular language).

If anyone is interested, I can provide you with some more details.  If I
get a lot of interest, I'll post a longer discussion to the net.

Kirt

-------------------------------------------------------------------------------
 Kirt Alan Winter                                        winter@hpldola.hp.com
 Hewlett Packard - EDD                                   (719) 590-5974
 Colorado Springs, Colorado
-------------------------------------------------------------------------------
 These ideas represent my opinions alone, not HP's (at least for now...).
-------------------------------------------------------------------------------

news@santra.UUCP (news) (05/06/88)

In article <3850009@wdl1.UUCP> rion@wdl1.UUCP (Rion Cassidy) writes:

>>Nassim Bouteldja wrote:
>>I have had to think about this issue for a company that practices 
>>programming-in-the-large (over 2 million lines of hll source code) with
>>the software having a long lifetime (>= 10 years). In an environment 
>>like this, where the readability (hence maintainability) of programs is
>>of paramount importance, I would not hesitate to promote style rules 
>>if I was convinced that they improve readability. 

>I can't claim a great deal of experience in this vien, but it seems to
>me that if you're producing that much code that has to be maintained
>for that long of a period, you should be doing code reviews,
>walkthroughs, or inspections as part of the implementation process
>simply to assure the correct functionality.

We certainly do have code reviews, but we would like to concentrate on
the logical design of the program. It is a bit time-consuming to start
checking on line lengths, procedure lengths, amount of spaces per line,
amount of blank lines, identifier lengths. It can nicely be implemented
as a program that produces metrics on these characteristics. I actually
built such a program and by just glancing at the results of the analysis
I can identify aspects that need closer physical checking. Because 
code reviews are done before system testing, it is inevitable that the
tested and validated programs will differ from the ones submitted at
code review meetings. Therefore, it is worthwhile running the style
metrics before allowing a program to be frozen in the project database.
Furthermore, when a program's life is long, it tends to be modified
along the way either to correct errors or for enhancement purposes. Often,
these kind of activities are not subject to code review checks. So my tool
can be used in those circumstances too, and in general to monitor one
aspect of software quality.