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

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

[harsha]

On Sep 17, 5:09 pm, Richard Heathfield <[e-mail]:

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]

On Sep 17, 4:48 pm, Christopher Key <[e-mail]:

>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]

Richard Heathfield wrote:

>

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

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.

>

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

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!

>

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

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.

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

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.

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

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]

harsha wrote:

On Sep 17, 4:48 pm, Christopher Key <[e-mail]:

>I was wondering if there are any style guides

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:

<snip>

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/200402090...h/c-predef.htm

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

[Michal Nazarewicz]

Christopher Key <cj***@cam.ac.ukwrites:

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.

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

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.

--
Best regards, _ _
.o. | Liege of Serenly Enlightened Majesty of o' \,=./ `o
..o | Computer Science, Michal "mina86" Nazarewicz (o o)
ooo +--<mina86*tlen.pl>---<jid:mina86*chrome.pl>--ooO--(_)--Ooo--

[David Thompson]

On Mon, 17 Sep 2007 12:48:47 +0100, Christopher Key <cj***@cam.ac.uk>
wrote:

<snip: releasing codeI 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.

<snip other points about casing>

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]

David Thompson wrote:

On Mon, 17 Sep 2007 12:48:47 +0100, Christopher Key <cj***@cam.ac.uk>
wrote:

><snip: releasing codeI 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?

--
Ian Collins.

[Richard Heathfield]

Ian Collins said:

David Thompson wrote:

>On Mon, 17 Sep 2007 12:48:47 +0100, Christopher Key <cj***@cam.ac.uk>
wrote:

>><snip: releasing codeI 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++.

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

[Ian Collins]

Chris Hills wrote:

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

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

[Richard Heathfield]

Chris Hills said:

In article <I7******************************@bt.com>, Richard Heathfield
<rj*@see.sig.invalidwrites

<snip>

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

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.

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