Coding Standards. was: a style question

[John D. Mitchell]

>In article <1990Nov10.191840.21113 at clear.com> rmartin at clear.com (Bob Martin) writes:
>
>At Clear we have instituted a style standard which
>all our engineers follow.  This standard specifies how indenting
>should be done, how variables, functions and types should be named.
>I specifies that functions should have single entrance and single
>exit points, and that functions should not be much longer then
>one page.  It specifies a documentation style and demands that
>comments always be placed on closing braces.  etc. etc.
>
I hate to jump into the middle of a religious war :-) but...
from working as a consultant/contractor, school (as a student), and
school (as a reader) I have found that it's not so much someone's
code formatting that makes such a big difference in ease of comprehension
but their design.  I have seen many bizarre (to me :-)) coding formats but
as long as it was halfway rational (read I could figure it out :-)) and
most of all CONSISTENT I could quickly adapt and understand the
meaning.  Sure there are cases where the code is all nice and tidy but
makes no sense, but each time it's the ambiguity of the design of
the [module|function|whatever] that's to blame (which of course was
the coder/designer's fault).  So make my life easier by being consistent.

As far as single entry/exit points go, I side with those who say
"It depends."  Again I stress the need for a clean design.  Sometimes
(ok so I'm moody! :-)) it works out nice for multiple return calls
and other times it doesn't.  I've been led to believe that we're
all supposed to be grown-ups and can make those kinds of decisions.
The trick for me is:  which way is the least complicated.

Naming.  What a mess.  You get everything from the minimalists (i, i2,
tmp, etc.) to those foreigners (:-)) at M#$@*soft with their
'Hungarian' notation.  Once again (boy I sure am repetitive!), it depends.
My style is still evolving.  I use my own (I think more consistent and
orthogonal) version of 'Hungarian' notation.  Hey, it works for me and
the way the rest of the name is (long and descriptive :-)) if you don't
understand the prefix you can just ignore it.


-----	John D. Mitchell
	johnm at cory.Berkeley.EDU