Note that this article is cross-posted to four
 groups.  If you follow up, please carefully choose
 which groups you follow up to...

In my humble opinion it is time that we, the community of
software engineers, charter a group to create an international
standard for C/C++ naming conventions.

This group should decide on appropriate conventions for naming
functions, variables, types, classes, member-variables,
member-functions, constants, macros, third-party-classnames, etc...

Once such a standard is in place, those of us that choose to use it
can increase the efficiency of communicating with one another.
Such increased efficiency will be very necessary over the next
decade as the number of engineeers, and the number of source lines
continues to increase geometrically.

--
+-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.     |

Somehow, I don't think that the people who gave us...

/*
 * Copyright (c) 1982, 1986, 1989 Regents of the University of California.
 * All rights reserved.
 *
 [ rest of the license deleted for brevity and I hope UCB's lawyers
   don't mind... -GW ]
 */
/* ARGSUSED */
execve(p, uap, retval)
 register struct proc *p;
 register struct args {
  char *fname;
  char **argp;
  char **envp;
 } *uap;
 int *retval;
{
 register nc;
 register char *cp;  /* GW: note all pointers end in p */
 register struct buf *bp;
 struct buf *tbp;
 int na, ne, ucp, ap, cc; /* GW: counts begin with n */
 unsigned len;
 int indir, uid, gid;
 char *sharg;   /* GW: "string" != "pointer" */
 struct vnode *vp;
 swblk_t bno;
 struct vattr vattr;
 char cfname[MAXCOMLEN + 1];
 char cfarg[MAXINTERP];
 union {
  char ex_shell[MAXINTERP]; /* #! and interpreter name */
  struct exec ex_exec;
#ifdef HPUXCOMPAT
  struct hpux_exec ex_hexec;
#endif
 } exdata;
#ifdef HPUXCOMPAT
 struct hpux_exec hhead;
#endif
 register struct ucred *cred = u.u_cred; /* GW: hysterical raisins? */
 register struct nameidata *ndp = &u.u_nd;
 int resid, error, flags = 0;

/* . . . */

would agree with the people who gave us the following examples from a
BYTE article by Simonyi and Heller...

wnFirst = wnLast; /* fragments */
*pwn = WnShowCp(cpLast);

AddLi(struct LI **ppliHead,
      struct LI *plItem)
  {
    pliItem->pliNext = *ppliHead;
    *ppliHead = pliItem;
  }

and all the like.  Consider that both of these examples are in the
style of considerable corpuses (corpi?) of code---the first from BSD
Unix and the second from Microsoft's programing standards.  [For the
people having the SLOC discussion, kern_exec.c is 665 lines long.]  If
we have this kind of a vast gulf (and these are probably two extreme
cases), with many different people who all believe that they have
found the One True variable naming standard, how on Earth can anyone
expect to come to a consensus.

I, for one, don't think that such standards are the least bit useful,
anyway.  [Especially Simonyi's idea... why should we have free-form
variable names if they are always used to indicate the type?  Isn't
that why we're not all programming in FORTRAN?  Karl Heuer aside, I
think that compilers should be linting code, not humans.]

-GAWollman

--
Garrett A. Wollman - wollman@emily.uvm.edu - kira!wollman

Disclaimer:  I'm not even sure this represents *my* opinion, never
mind UVM's, EMBA's, EMBA-CF's, or indeed anyone else's.

rmartin@clear.com (Bob Martin) writes:
> In my humble opinion it is time that we, the community of
> software engineers, charter a group to create an international
> standard for C/C++ naming conventions.

wollman@emily.uvm.edu (Garrett Wollman) replies:
> Somehow, I don't think that the people who gave us...
> [two pieces of code using radically different naming conventions]
> ...
> If we have this kind of a vast gulf (and these are probably two extreme
> cases), with many different people who all believe that they have
> found the One True variable naming standard, how on Earth can anyone
> expect to come to a consensus.

Garrett makes an excellent point.  Naming standards are often quite
arbitrary, based as much on individual preferences as on more objective
criteria.  An attempt to define a universal standard is likely to meet
enormous resistance.

I think you'll find that people are more receptive to general guidelines
than hard-and-fast rules.  The issue of indentation and bracket placement
is a good example.  I doubt you'll get much argument if you assert that
the following exhibits poor coding style:

 char *check (l,n,s) char **l, *s; int n;
 { int d, m, l = 0, r = n - 1;
 do { m = (l + r) / 2;
  d = strcmp(s, l[m]);
  if (d < 0) r = m - 1;
  else if (diff > 0) l = m + 1;
  else return(l[m]); } while (l <= r);
 return(0); }

However, you'll have a holy war on your hands if you try to champion a
_particular_ style, say, Whitesmith over K&R.

The same applies to symbol naming.  A list of do's and don'ts, each with
justification and code examples, will be much more palatable to the C
language community than a standard which specifies a different formula
for each syntactic element.

Here are a few that I personally consider important.  These are only
_examples_; please don't anyone use them as an excuse for a flame war!

 -  Give symbols meaningful names, but don't use excessively long names
    or baroque capitalization in a heroic attempt to encode scope, type,
    and usage information.  This actually _decreases_ readability,
    because a programmer has to scan large amounts of redundant text and
    line-breaks.  So don't use
 _LIBC_FILEIO_StandardOutputDescriptorP
    if
 stdout
    will do.  (`stdout' is admittedly rather terse for a global symbol,
    but you get the idea.)  Likewise,
 for ( cur_node = list->head; cur_node; cur_node = cur_node->next )
    conveys just as much information as
 for ( currentNodePointer = linkedList->headNode;
       currentNodePointer != NullLinkedListNode;
       currentNodePointer = currentNodePointer->nextNode )

 -  Libraries and their header files should not define overly generic
    names.  The X11 library and Intrisincs headers, for example, define
    Arg, Status, Bool, Boolean, and a host of other types which are not
    germane to window systems.  This greatly increases the likelihood of
    conflicts with application-defined types.  Consistent use of a short
    module prefix helps to avoid this problem.  Example:

 typedef struct _TREE_NODE {
     struct _TREE_NODE *left, *right;
     void *data;
 } TREE_NODE;
 extern TREE_NODE *tree_add(), *tree_remove();
 extern tree_traverse();

    is preferable to

 typedef struct _NODE {
     struct _NODE *left, *right;
     void *data;
 } NODE;
 extern NODE *add(), *remove();
 extern traverse();

 -  Parametric macro names should be easily distinguishable from
    procedure names, as an indication to the programmer that their
    parameters may be instanced more than once.  A common convention is
    to define macros using all uppercase letters.

And so on.

(Note: four groups for a discussion like this seems a bit excessive.
I've directed followups to comp.{lang,std}.c only, on the (perhaps
invalid) assumption that C++ programmers read the C groups.  If you
disagree, just change the Followup-To: line.)


chris ross   <cjross@bbn.com>  BBN Advanced Simulations  (617) 873-3272
  Lisp in action is like a finely choreographed ballet.
   Ada in action is like a waltz of drugged elephants.
      C in action is like a sword dance on a freshly waxed floor.

> In my humble opinion it is time that we, the community of
> software engineers, charter a group to create an international
> standard for C/C++ naming conventions.
>
> This group should decide on appropriate conventions for naming
> functions, variables, types, classes, member-variables,
> member-functions, constants, macros, third-party-classnames, etc...

Mercy-please, no.  The last thing we need is to see nice, readable names
degenerate into alphabet soup with mixtures of majuscule and miniscule.

What we COULD use are standards for making `global' variables member static,
etc.  I'll buy limited suggestions for capitalization, but remember that
in C++ you sometimes deliberately blur the distinction between object,
function, and type.

We could ALSO use some standards on what is NOT done with the preprocessor,
and perhaps on INTERIM forms for `fake templates' via the preprocessor.  And
for preprocessor-activated debugging.  (Perhaps we could assume inheritance
from a `debug' type in certain macros?)

We could also do with some sanity in what NOT to do with templates and
exceptions, and minimum requirements for typedef-from-built-in-to-subject-
type-to-application-type sequences.

We might even call for vendor classes to be internal public inside a top-level
class for the vendor, with the user code typedefing them out.  If the
internal and external names are the same (as they would be most of the time)
constructor and destructor names should be sane.

Have you considered what the extra characters might do to name mangling
schemes that append type name upon type name, BTW?  Since C++ has the
support for type discrimination and scoped naming, let's agree to use them
instead of trying to layer another layer on the existing system.  If the
mechanisms are NOT adequate, let's go to X3J16 with an explanation of why.

But what we don't need, won't miss, and will mourn the day we adopt (he
pleaded on his knees) is a set of rules that require perfectly good
identifiers to be turned into alphabet soup BEFORE C++ name-mangles them.
I worked on a C project that used such, and they did no good and caused
minor agony.  In C++, with its better typechecking, typesafe linking, and
greater number of syntactic/semantic categories, they would do no good and
cause greater agony.

(This programmer's opinion, of course.)
--

 (This man's opinions are his own.)
 From mole-end    Mark Terribile