Coding style

[Christopher Key]

Hello,

I've some code which I'd like to release in object form along with a
suitable header. Before I do this however, I'd like to finalise the
exact names for everything declared in the header, and want to make sure
that I make the right choice, both with regards readability and
following existing standards. I was wondering if there are any style
guides or what peoples opinions are on the following:

1) Everything declared starts with a unique identifier, e.g. xyz_. How
should this be capitalised, and how many trailing underscores. Two
existing examples are:

gd... and FLAC__...

2) At present, all my function are named along the lines of
xyz_do_something(). The alternatives seems to be xyz_DoSomething or
xyz_doSomething, any precedent?

3) My typdefs are all similarly named, e.g. xyz_my_typdef. Is it
sensible to capitalise these to distinguish them?

4) Typedefs involving structs and the structs themselves are identically
named, e.g.

typdef struct xyz_a xyz_a;

// Later

struct xyz_a {
...
}

is this sensible?


Does anyone have any thoughts on the above, or is it all just down to
personal preference?


Regards,

Chris

 

[Richard Heathfield]

Christopher Key said:

Hello,

I've some code which I'd like to release in object form along with a
suitable header. Before I do this however, I'd like to finalise the
exact names for everything declared in the header

[...]

The scheme you describe makes sense. A three-letter prefix followed by an
underscore is a sensible idea (avoid is* and to*, though, since following
these with a letter clashes with the namespace that the C Standard
reserves for implementations - you neatly sidestep str* and mem* by way of
your underscore, so don't worry about those).

1) Everything declared starts with a unique identifier, e.g. xyz_. How
should this be capitalised, and how many trailing underscores. Two
existing examples are:

gd... and FLAC__...

Up to you. Keep it easy-to-type, and your users will hate you less.

2) At present, all my function are named along the lines of
xyz_do_something(). The alternatives seems to be xyz_DoSomething or
xyz_doSomething, any precedent?

Take your pick. All three variants are common. But if your functions work
on your own types, why not use the type name (or an abbrev thereof) in the
function name? For example, if you have a type called xyz_cuddlytoy, you
could give functions names like xyz_cuddlytoy_squeak, xyz_cuddlytoy_blink,
and so on.

3) My typdefs are all similarly named, e.g. xyz_my_typdef. Is it
sensible to capitalise these to distinguish them?

Do you mean Mixed Case, or UPPER CASE?

I used to use UPPER CASE for type names. I don't any more. But it's a
viable style. Although most C programmers like to think of UPPER CASE as
being reserved for macros, in practice I never encountered any ambiguities
in real code that made me wonder what I was looking at - a macro or a type
synonym. But I guess I just kind of went off the idea.

Mixed Case is fine too, although - again - it's a style I tried and
eventually dumped. Nothing wrong with it - I think I just got tired of it,
really.

4) Typedefs involving structs and the structs themselves are identically
named, e.g.

typdef struct xyz_a xyz_a;

// Later

struct xyz_a {
...
}

is this sensible?

Yes, but I suggest a trailing underscore on the tag name: typedef struct
xyz_a_ xyz_a. This disambiguates the tag from the synonym for the benefit
of Visual Studio users' "jump to definition" feature).

And separating the typedef from the type definition, as you have done here,
is eminently sensible in my opinion.

My opinion on both these points is perhaps non-representative of the
general clc opinion. Some people just love to type.

Does anyone have any thoughts on the above, or is it all just down to
personal preference?

As long as you steer clear of the implementation namespace, it's pretty
much down to you in the end. Pick a sensible style and stick to it
throughout the library. (By the time you've finished it, you may well be
sick of it, but you can always do something different for your /next/
library, although it might annoy those who want to use both.)

 

[harsha]

Christopher Key said:

Hello,

I've some code which I'd like to release in object form along with a
suitable header. Before I do this however, I'd like to finalise the
exact names for everything declared in the header

[...]

The scheme you describe makes sense. A three-letter prefix followed by an
underscore is a sensible idea (avoid is* and to*, though, since following
these with a letter clashes with the namespace that the C Standard
reserves for implementations - you neatly sidestep str* and mem* by way of
your underscore, so don't worry about those).

1) Everything declared starts with a unique identifier, e.g. xyz_. How
should this be capitalised, and how many trailing underscores. Two
existing examples are:

gd... and FLAC__...

Up to you. Keep it easy-to-type, and your users will hate you less.

2) At present, all my function are named along the lines of
xyz_do_something(). The alternatives seems to be xyz_DoSomething or
xyz_doSomething, any precedent?

Take your pick. All three variants are common. But if your functions work
on your own types, why not use the type name (or an abbrev thereof) in the
function name? For example, if you have a type called xyz_cuddlytoy, you
could give functions names like xyz_cuddlytoy_squeak, xyz_cuddlytoy_blink,
and so on.

3) My typdefs are all similarly named, e.g. xyz_my_typdef. Is it
sensible to capitalise these to distinguish them?

Do you mean Mixed Case, or UPPER CASE?

I used to use UPPER CASE for type names. I don't any more. But it's a
viable style. Although most C programmers like to think of UPPER CASE as
being reserved for macros, in practice I never encountered any ambiguities
in real code that made me wonder what I was looking at - a macro or a type
synonym. But I guess I just kind of went off the idea.

Mixed Case is fine too, although - again - it's a style I tried and
eventually dumped. Nothing wrong with it - I think I just got tired of it,
really.

4) Typedefs involving structs and the structs themselves are identically
named, e.g.

typdef struct xyz_a xyz_a;

// Later

struct xyz_a {
...
}

is this sensible?

Yes, but I suggest a trailing underscore on the tag name: typedef struct
xyz_a_ xyz_a. This disambiguates the tag from the synonym for the benefit
of Visual Studio users' "jump to definition" feature).

And separating the typedef from the type definition, as you have done here,
is eminently sensible in my opinion.

My opinion on both these points is perhaps non-representative of the
general clc opinion. Some people just love to type.

Does anyone have any thoughts on the above, or is it all just down to
personal preference?

As long as you steer clear of the implementation namespace, it's pretty
much down to you in the end. Pick a sensible style and stick to it
throughout the library. (By the time you've finished it, you may well be
sick of it, but you can always do something different for your /next/
library, although it might annoy those who want to use both.)

--
Richard Heathfield <http://www.cpax.org.uk>
Email: -www. +rjh@
Google users: <http://www.cpax.org.uk/prg/writings/googly.php>
"Usenet is a strange place" - dmr 29 July 1999

HI..
you might find this useful.
coding conventions-> http://sajjanharudit.googlepages.com/template.html

 

[harsha]

I was wondering if there are any style guides

HI..
you might find this useful.
coding conventions-> http://sajjanharudit.googlepages.com/template.html

 

[Christopher Key]

Up to you. Keep it easy-to-type, and your users will hate you less.

Indeed, lower case followed by an underscore seems a good compromise.
The underscore allows it to stand out, and I for one find lower case
rather easier to type.

Take your pick. All three variants are common. But if your functions work
on your own types, why not use the type name (or an abbrev thereof) in the
function name? For example, if you have a type called xyz_cuddlytoy, you
could give functions names like xyz_cuddlytoy_squeak, xyz_cuddlytoy_blink,
and so on.

Again, that's how things are at present, and given your advice, I think
I'll keep it. I've strictly kept everything named as xyz_cuddlytoy_...
in anticipation of future expansion, e.g. xyz_actiontoy_squeak!

Do you mean Mixed Case, or UPPER CASE?

I used to use UPPER CASE for type names. I don't any more. But it's a
viable style. Although most C programmers like to think of UPPER CASE as
being reserved for macros, in practice I never encountered any ambiguities
in real code that made me wonder what I was looking at - a macro or a type
synonym. But I guess I just kind of went off the idea.

Mixed Case is fine too, although - again - it's a style I tried and
eventually dumped. Nothing wrong with it - I think I just got tired of it,
really.

I was intending mixed case, and am still not sure. On the one hand, it
does distinguish types from functions when looking at the code, but
isn't as easy to type. For people not familiar with the library, it may
also be a little difficult to remember where to capitalise, e.g.
xyz_CuddlyToy or xyz_Cuddlytoy.

Yes, but I suggest a trailing underscore on the tag name: typedef struct
xyz_a_ xyz_a. This disambiguates the tag from the synonym for the benefit
of Visual Studio users' "jump to definition" feature).

Thanks, will do so. I wasn't aware of any situations where one would
want to refer to the struct defition itself, but this is certainly one.

And separating the typedef from the type definition, as you have done here,
is eminently sensible in my opinion.

It's a nice trick that I came across recently while searching for a way
to allow circular definitions. It also allows opaque definitions rather
nicely, as the typedef can go in the public header, and the struct
itself in a private header.

As long as you steer clear of the implementation namespace, it's pretty
much down to you in the end. Pick a sensible style and stick to it
throughout the library. (By the time you've finished it, you may well be
sick of it, but you can always do something different for your /next/
library, although it might annoy those who want to use both.)

Thanks for the advice, seems like the general rule is to do what seems
right and hope others agree. One final point, is there a concise,
definitive list of names to avoid, e.g. names beginning mem*, names
ending _t etc?

Regards,

Chris

 

[Christopher Key]

HI..
you might find this useful.
coding conventions-> http://sajjanharudit.googlepages.com/template.html

Thanks,

I've had a read through. I do agree with all the spacing and commenting
guidelines, although I have to say that camelCase variables and
functions just don't look right to my eye. It's strange, because I
prefer that style in perl, although I've absolutely no idea why!

Regards,

Chris

 

[Richard Heathfield]

Christopher Key said:

Thanks for the advice, seems like the general rule is to do what seems
right and hope others agree.

Pretty much, yes.

One final point, is there a concise,

No.

definitive list of names to avoid, e.g. names beginning mem*, names
ending _t etc?

Here's a good starting point, although it only covers ISO, not POSIX (e.g.
it doesn't mention the _t suffix):

http://web.archive.org/web/20040209031039/http://oakroadsystems.com/tech/c-predef.htm

 

[Michal Nazarewicz]

I was intending mixed case, and am still not sure. On the one hand,
it does distinguish types from functions when looking at the code, but
isn't as easy to type. For people not familiar with the library, it
may also be a little difficult to remember where to
capitalise, e.g. xyz_CuddlyToy or xyz_Cuddlytoy.

For user not familiar with the library it may also be a little difficult
to remeber where to put underscore, e.g. xyz_cuddly_toy or
xyz_cuddlytoy.

My personal opinion is as follows: If your names contain underscore
don't use camel case (ie. xyz_cuddly_toy). If you intend to capitalise
don't use underscore and do not capitalise the first letter,
(ie. xyzCuddlyToy). But that's only my opinion.

It's a nice trick that I came across recently while searching for
a way to allow circular definitions. It also allows opaque
definitions rather nicely, as the typedef can go in the public header,
and the struct itself in a private header.

You can use a full name, ie. "struct foo" instead of typedef, ie.:

#v+
struct slist {
struct slist *next;
void *data;
};
#v-

also in header files you can put single "struct slist;". In the past
I have used typedefs but recently I've stopped using them.

Thanks for the advice, seems like the general rule is to do what seems
right and hope others agree. One final point, is there a concise,
definitive list of names to avoid, e.g. names beginning mem*, names
ending _t etc?

If you start all your names with "xyz_" you should be fine, however IIRC
all identifiers ending with "_t" are reserved by POSIX standard and all
(or some) identifiers starting with a underscore are reserved by
C standard. So I would avoid those two.

 

[David Thompson]

<snip: releasing code> I was wondering if there are any style
guides or what peoples opinions are on the following:

1) Everything declared starts with a unique identifier, e.g. xyz_. How
should this be capitalised, and how many trailing underscores. Two
existing examples are:

gd... and FLAC__...

Double underscores are legal in C but not C++. While not all C needs
to be usable from C++, I personally would avoid introducing even a
small incompatibility 'cost' for, as I see it, zero benefit. Even
ignoring that, in many cases (fonts, displays, etc.) underscores run
together and it's easy to 'mismeasure' visually; this is more a
problem above 3, but does occur sometimes even for 2.

Does anyone have any thoughts on the above, or is it all just down to
personal preference?

No comment. All the variants you considered are used, AFAICT
successfully. I assume you don't have standards set by a formal group
(e.g. a company) or the community you are releasing to as e.g. perl
folks do; if so you probably wouldn't have asked. If you have a
preference, I say go with it. Obviously, whatever you choose, use it
consistently; given you care(d) enough to ask, I expect you will.

- formerly david.thompson1 || achar(64) || worldnet.att.net

 

[Ian Collins]

Double underscores are legal in C but not C++.

Says who?

 

[Richard Heathfield]

Ian Collins said:

Says who?

Says ISO/IEC 14882:1998, which contains the following paragraph:

17.4.3.1.2 Global names [lib.global.names]
1 Certain sets of names and function signatures are always reserved to
the implementation:
- Each name that contains a double underscore (_ _) or begins with an
underscore followed by an upper-case letter (2.11) is reserved to the
implementation for any use.

I suggest that it might be wiser to take further discussion of this
question to comp.lang.c++.

 

[Chris Hills]

Ian Collins said:

Says who?

Says ISO/IEC 14882:1998, which contains the following paragraph:

17.4.3.1.2 Global names [lib.global.names]
1 Certain sets of names and function signatures are always reserved to
the implementation:
- Each name that contains a double underscore (_ _) or begins with an
underscore followed by an upper-case letter (2.11) is reserved to the
implementation for any use.

I suggest that it might be wiser to take further discussion of this
question to comp.lang.c++.

Here we go again... as soon as some one mentions C++ you run from it
like vampires from sun light.

It will not hurt to discuss the differences between C and C++ here. If
comp.lan.c++ too the same attitude there would be nowhere to discuss the
interaction between C and C++.

It isn't going to hurt anyone to discuss it here.

 

[Joachim Schmitz]

Ian Collins said:

David Thompson wrote:
<snip: releasing code> I was wondering if there are any style
guides or what peoples opinions are on the following:

1) Everything declared starts with a unique identifier, e.g. xyz_.
How
should this be capitalised, and how many trailing underscores. Two
existing examples are:

gd... and FLAC__...

Double underscores are legal in C but not C++.

Says who?

Says ISO/IEC 14882:1998, which contains the following paragraph:

17.4.3.1.2 Global names [lib.global.names]
1 Certain sets of names and function signatures are always reserved to
the implementation:
- Each name that contains a double underscore (_ _) or begins with an
underscore followed by an upper-case letter (2.11) is reserved to the
implementation for any use.

I suggest that it might be wiser to take further discussion of this
question to comp.lang.c++.

Here we go again... as soon as some one mentions C++ you run from it like
vampires from sun light.

It will not hurt to discuss the differences between C and C++ here. If
comp.lan.c++ too the same attitude there would be nowhere to discuss the
interaction between C and C++.

It isn't going to hurt anyone to discuss it here.

There not much point discussing it _just_ here, nor _just_ there. This is a
good case for crossposting though.

Bye, Jojo

 

[Ian Collins]

Here we go again... as soon as some one mentions C++ you run from it
like vampires from sun light.

I got this one wrong, it happens. There isn't anything left to say.

 

[Richard Heathfield]

Chris Hills said:

Here we go again... as soon as some one mentions C++ you run from it
like vampires from sun light.

On the contrary, I answered the question fully, and provided appropriate
redirection, should the OP wish to check my answer with C++ experts. That
seems reasonable to me.

Chris, obviously disagreement and discussion are par for the course in
comp.lang.c, but recently it seems that your replies to my articles have
become hostile rather than merely disputational; several have been
childish; and one has been dishonest. I've tried very hard not to see you
as a troll, but I can no longer see how I can justify that.

I'll review the situation in 30 days.

 

[CBFalconer]

Ian Collins said:

David Thompson wrote:
.... snip ...

Double underscores are legal in C but not C++.

Says who?

Says ISO/IEC 14882:1998, which contains the following paragraph:

17.4.3.1.2 Global names [lib.global.names]
1 Certain sets of names and function signatures are always
reserved to the implementation:
- Each name that contains a double underscore (_ _) or begins
with an underscore followed by an upper-case letter (2.11) is
reserved to the implementation for any use.

I suggest that it might be wiser to take further discussion of
this question to comp.lang.c++.

Here we go again... as soon as some one mentions C++ you run from
it like vampires from sun light.

It will not hurt to discuss the differences between C and C++
here. If comp.lan.c++ too the same attitude there would be nowhere
to discuss the interaction between C and C++.

It isn't going to hurt anyone to discuss it here.

For once, I have to agree with you. However such discussions
should be limited to the language differences and interactions.
The problem is that any C/C++ crosspost seems to invariably lead to
thoroughly off-topic material. In this case the matter of interest
to C'ers is that '__' is illegal in C++. The end.