New coding standards: use underscores, hyphens or mixed case in command (and identifier) names

[Emmanuel Delahaye]

James Harris vient de nous annoncer :

I was thinking of executable file names, mainly.

Hence, it's hardly a C-question.

Hence the hyphenated
versions. I was thinking of the user having to type the command to run the
program so,

helloworld
hello-world
hello_world
helloWorld
HelloWorld

I know a file name format is not C per se but it is often used to run a C
program - my only excuse for including it in this NG.

There is no such a thing like a C-program. One one hand, you have
C-sources, and on the other hand, you have executables. Who knows/cares
about the original language it was written in ?

 

[Gregory Pietsch]

Before I embark on a new long-term project I'd appreciate your advice on how to split up
long names. I would like to keep the standards for command names the same as that for
variable names. Looking at the examples below, which ones seem better?

Everyone has his own style, so everyone has his own opinions. Here's
my particular style of naming:

* Use internal underscores to separate words.
* Types are in uppercase and end with _T .
* Enumeration values and macro names are in uppercase.
* Synonyms for types generated via typedef have the same name as the
struct or union tag that is being synonymed; e.g.

typedef struct TAG_T {
/* ... */
} TAG_T;

* Headers should include header guards to prevent multiple inclusion;
e.g.

#ifndef FILE_H
#define FILE_H
/* rest of header goes here */
#endif

The header guard has the same name as the filename, but in all
uppercase and all punctuation turned into underscores. It ends with _H
..

* Variable names are in lowercase, and each declared variable should
be in its own declaration.
* Function names should start with either a verb or a common slug
followed by a verb (e.g. DS_create, DS_destroy). They should be in
lowercase except that the slug should be in uppercase if it is there.
Cool verbs to use include "copy", "create" (bring something into
existence), "destroy" (the opposite of "create"), "get", "set", and
"transmogrify". But whatever you use, the action must be clear enough
for a ten-year-old.
* Function names that indicate a Boolean response should return int; a
nonzero value (preferably 1) indicates true and 0 indicates false. The
function name should not contain a negative word such as "not",
"non-", "never", or something similar. The phrase "is_" is a perfect
starter for a function, but the underscore must be there because "is"
followed by a non-underscore is reserved.

* Use K&R style braces, four-character indents, and no tabs.
* Lines should have no more than 78 characters.
* The switch statement should have a default case.

If there's anything I've left out, add it. I'm not going to act as the
code police. Incidental flaws can be covered with the "indent"
program, available wherever GNU products are downloaded from.

Gregory Pietsch

 

[Arthur J. O'Dwyer]

Everyone has his own style, so everyone has his own opinions.

Yes indeed. Here's some of mine.

* Types are in uppercase and end with _T .

This /could/ get confusing, if you also use more than the average
quantity of macros. I prefer 'CamelCase' for OO-style typedef'ed
struct types, and '[struct|union|enum] plainoldc' for the rest; this
avoids confusion completely. Your '_T' suffix is a pretty good way
to avoid confusion with macros, too, though.

* Synonyms for types generated via typedef have the same name as the
struct or union tag that is being synonymed; e.g.

typedef struct TAG_T {
/* ... */
} TAG_T;

Better style (IMO, but note that I /am/ claiming this is objectively
better) is to write the typedef first: replace

typedef struct TAG_T {
FOO_T data;
struct TAG_T *next;
} TAG_T;

with

typedef struct TAG_T TAG_T;
struct TAG_T {
FOO_T data;
TAG_T *next;
}

Slightly more typing, but you get the benefit of being able to
use the typedef-name 'TAG_T' inside the structure definition
itself, just the way client code will get to use it.

* Headers should include header guards to prevent multiple inclusion;
e.g.

#ifndef FILE_H
#define FILE_H
/* rest of header goes here */
#endif

The header guard has the same name as the filename, but in all
uppercase and all punctuation turned into underscores. It ends with _H

Header guards are good, but again IMO it is better to replace
'FILE_H' with 'H_FILE'. This removes a pedantic objection to

#define ELEPHANT_H /* Undefined behavior, name "E..." reserved! */

and means you don't have to come up with a special-case naming
convention in that one circumstance.

* Use K&R style braces, four-character indents, and no tabs.
* Lines should have no more than 78 characters.

Hear hear!

-Arthur

 

[Dan Pop]

Don't be so hasty. I am thinking, I am THINKING...

If you really were, you'd have easily realised that your question
belonged to private email, rather than gratuitously abusing the newsgroup.

Dan

 

[Ronald Landheer-Cieslak]

Before I embark on a new long-term project I'd appreciate your advice on how to split up
long names. I would like to keep the standards for command names the same as that for
variable names. Looking at the examples below, which ones seem better?

Straight names
echoclient
lastcharoffset
helloworld

Internal underscores
echo_client
last_char_offset
hello_world

I could also use embedded hyphens as my minus sign must be surrounded by whitespace
(please suspend disbelief while looking at these. I know they will look unfamiliar!)
echo-client
last-char-offset
hello-world

Mixed case
EchoClient
LastCharOffset
HelloWorld

Initial lower case then mixed
echoClient
lastCharOffset
helloWorld

In some ways I like the mixed case versions using an inital capital, especially as I may
want to prefix some names with a code for an abstract data type, which, when present,
could begin with a lower case. Is this getting too Microsoft-ish? Is it getting to
Hungarian? Is Hungarian bad when used with abstract data types rather than inbuilt ones?

IMHO, Hungarian is *always* bad: it lies.

Advice on which is or is not thought to be acceptable would be much appreciated. Please
bear in mind that I intend these names for commands/instructions as well as variables and
types. Constants would be in all caps.

I'd go for the words_separated_by_underscores. Don't "encode" types in
your identifier names - just functionality: functionality doesn't lie
(and you'll be far more inclined to change the name of a function when
its functionality changes than when its return type changes).

There's no reason to make constants all-caps, by the way: why would you
want to do that?

rlc

 

[Dan Pop]

There's no reason to make constants all-caps, by the way: why would you
want to do that?

To make it obvious that they are constants and, therefore, usable in
constant expressions. As an additional bonus, the programmers would be
less tempted to change their values ;-)

Dan

 

[Sam Halliday]

If you really were, you'd have easily realised that your question
belonged to private email, rather than gratuitously abusing the newsgroup.

hes joking (some "the other" James S Harris thing).

additionally, if you looked at the original poster you would see he has "James
Harris" <no.email.please>, therefore private correspondence is out of the
question.

 

[Dan Pop]

hes joking (some "the other" James S Harris thing).

His joke didn't make any sense in the c.l.c context.

additionally, if you looked at the original poster you would see he has "James
Harris" <no.email.please>, therefore private correspondence is out of the
question.

And do you have the slightest clue about what this means? It means that
the OP is not interested in *any* discussions of a private nature (among
other things). Therefore, kal should have taken the hint.

Dan

 

[Sam Halliday]

And do you have the slightest clue about what this means? It means that
the OP is not interested in *any* discussions of a private nature (among
other things). Therefore, kal should have taken the hint

not necessarily. i do not show my email address on newsgroups (when possible) as
i got hit very hard by the last SWEN worm (SWEN is NEWS spelt backwards... a
reference to its email collection method) and spammers often use newsgroups to
collect email addresses. this does not mean i am against private correspondence.

 

[Richard Bos]

There's no reason to make constants all-caps, by the way: why would you
want to do that?

For one thing, because of the difference between

#define TWICE(i) ((i)+(i))

int x, y=4;
x=TWICE(y++);

and

int twice(int i)
{
return i+i;
}

int x, y=4;
x=twice(y++);

Making all #defined macros, both object- and function-like, all-caps, is
generally considered a good idea because they can have quite different
semantics from ordinary objects and functions.

Richard

 

[Ronald Landheer-Cieslak]

For one thing, because of the difference between

#define TWICE(i) ((i)+(i))

int x, y=4;
x=TWICE(y++);

and

int twice(int i)
{
return i+i;
}

int x, y=4;
x=twice(y++);

Making all #defined macros, both object- and function-like, all-caps, is
generally considered a good idea because they can have quite different
semantics from ordinary objects and functions.

Almost convincing

Thing is: macros that evaluate their parameters more than once are evil:
they shouldn't be written in the first place. Basically, macros that
have different semantics than their equivalent functions are confusing
and therefore harmful.

Macros *can* be good, but some *definitely* aren't.

Just my $0.02 CAN

rlc

 

[Ronald Landheer-Cieslak]

To make it obvious that they are constants and, therefore, usable in
constant expressions. As an additional bonus, the programmers would be
less tempted to change their values ;-)

The compiler will holler if you try to use non-constants in constant
expressions and if you try to change constants. The const-ness of an
identifier should be obvious from its function (e.g. a maximal anything
doesn't change, nor does a minimal anything, etc.). You don't need
all-caps for that.

rlc

 

[Dan Pop]

not necessarily. i do not show my email address on newsgroups (when possible) as
i got hit very hard by the last SWEN worm (SWEN is NEWS spelt backwards... a
reference to its email collection method) and spammers often use newsgroups to
collect email addresses. this does not mean i am against private correspondence.

People who are not against private communication provide a garbled
email address and an algorithm for degarbling it. You've got dozens of
examples in this very newsgroup. Not doing that means exactly one thing:
complete lack of interest in private communication.

Dan

 

[Sam Halliday]

People who are not against private communication provide a garbled
email address and an algorithm for degarbling it. You've got dozens of
examples in this very newsgroup. Not doing that means exactly one thing:
complete lack of interest in private communication.

thats unsound logic. it does not mean exactly one thing at all. it means that
"lack of interest in private communication" is one possible explanation.

 

[Keith Thompson]

Thing is: macros that evaluate their parameters more than once are
evil: they shouldn't be written in the first place. Basically, macros
that have different semantics than their equivalent functions are
confusing and therefore harmful.

Macros *can* be good, but some *definitely* aren't.

I think that's over-stating it a bit.

Macros that evaluate their parameters more than once impose a cost in
terms of maintainability. But there are circumstances in which that
cost is worthwhile. The getc macro in <stdio.h> is a good example of
this; by allowing the stream argument to be evaluated more than once,
it saves the overhead of a function call in most cases.

(An inline function might have been a better way to do this, but C
didn't have inline functions before C99.)

 

[Dan Pop]

thats unsound logic. it does not mean exactly one thing at all. it means that
"lack of interest in private communication" is one possible explanation.

The only *sensible* one.

Dan

 

[Dan Pop]

The compiler will holler if you try to use non-constants in constant
expressions and if you try to change constants.

But not the other way round: if the maintainer fails to realise that the
identifier is a constant that could be used in a constant expression,
there is no one to tell him about it.

The const-ness of an
identifier should be obvious from its function (e.g. a maximal anything
doesn't change, nor does a minimal anything, etc.).

In C, there is more than way of defining such constants:

#define MAXVAL 1000 /* MAXVAL can be used in constant expressions */
vs
const int maxval = 1000; /* no maxval in constant expressions */

You don't need all-caps for that.

Even if you don't need them, they certainly help. Have a look at the
constants defined in <limits.h> and <float.h> and see how many of them
aren't all caps.

Dan

 

[Dan Pop]

Thing is: macros that evaluate their parameters more than once are evil:
they shouldn't be written in the first place.

Sez who?

Basically, macros that
have different semantics than their equivalent functions are confusing
and therefore harmful.

That's why they're spelled all caps: to avoid having them confused with
functions. If you know you're "calling" a function-like macro, you
don't expect function call semantics and avoid side effects in the
arguments. No confusion and, therefore, no harm. Such macros can still
be very useful and it is sheer stupidity to avoid them simply because you
can't implement them with function semantics.

Macros *can* be good, but some *definitely* aren't.

Indeed. The ones that actually mess with the language syntax (see
"algol.h" in the original Bourne shell source code) are to be avoided
like the plague, outside of IOCCC contests.

Dan

 

[Ronald Landheer-Cieslak]

I think that's over-stating it a bit.

Macros that evaluate their parameters more than once impose a cost in
terms of maintainability. But there are circumstances in which that
cost is worthwhile. The getc macro in <stdio.h> is a good example of
this; by allowing the stream argument to be evaluated more than once,
it saves the overhead of a function call in most cases.

(An inline function might have been a better way to do this, but C
didn't have inline functions before C99.)

An inline function would have been a better way to do that and since
they exist since C99, why not use them and declare macros that evaluate
their parameters more than once a no-no..?

rlc

 

[Ronald Landheer-Cieslak]

Sez who?

Erhm.. let's see:
^^^^^^^^^^^^^^^^^^^^^^^
I guess that would be me

That's why they're spelled all caps: to avoid having them confused with
functions. If you know you're "calling" a function-like macro, you
don't expect function call semantics and avoid side effects in the
arguments. No confusion and, therefore, no harm. Such macros can still
be very useful and it is sheer stupidity to avoid them simply because you
can't implement them with function semantics.

In my experience, one can hardly ever rely on a naming convention to be
followed correctly & completely.

That aside, if you have to look up the semantics of your macros every
time you use them, just because they're macros, don't you think you're
kinda defeating the purpose of your macro?

In most cases, inline functions would do just as nicely without the
trouble that macros can cause (and C99 allows them, so why not use them?)

Indeed. The ones that actually mess with the language syntax (see
"algol.h" in the original Bourne shell source code) are to be avoided
like the plague, outside of IOCCC contests.

At least we agree on that

rlc