May 2013 coding style discussion thread

[Barney McGrew]

The C standard library seems to alternate between uppercase and lowercase identifiers for typedefs. On the one hand you have FILE which is an opaque type for storing the state of a stream, and on the other you have various numeric types like size_t, time_t, clock_t, etc. The choice of style seems to vary based on what the typedef is for, rather than it simply being a typedef.

Personally, if an identifier's a typedef I capitalise it (e.g. Foobar), if it's an enumeration member or a macro I make it uppercase, and I just use lowercase for everything else.

[phantomotap]

For example, you cannot dereference an opaque pointer since the definition of the type of what the pointer points to is unknown at that point.

O_o

I see.

You'd still get reference semantics which is poorly considered if the thing you are using looks like it should have value semantics.

*shrug*

Well, okay, I'm assuming you are talking about C instead of C++; with C++ you could just wrap for value semantics if you wanted.

With that in mind, I don't think an opaque pointer is a place for `typedef' pointer. If you don't have the `typedef', the reference semantics are obvious from the use. (The type you use doesn't look like it might have value semantics.) The type, because it is undefined, firewalls itself from chasing the pointer, accessing members, or attempting to create an instance, without whatever intended interface, due to all failing with compiler errors. It isn't as if you could directly use it, such as member access with `.', in any event.

On the one hand you have FILE

If I remember my history, `FILE' was originally an alias for an unspecified structure from before the days when `typedef' was a thing. In other words, `FILE' was a macro, and it was standardized under the assumption because it does not have to be a type. (The only standard interface deals with pointers so the actual thing used could just be an integer value treated specially by the underling system of really anything at all.)

Soma

[laserlight]

You'd still get reference semantics which is poorly considered if the thing you are using looks like it should have value semantics.

*shrug*

Well, okay, I'm assuming you are talking about C instead of C++; with C++ you could just wrap for value semantics if you wanted.

With that in mind, I don't think an opaque pointer is a place for `typedef' pointer. If you don't have the `typedef', the reference semantics are obvious from the use. (The type you use doesn't look like it might have value semantics.) The type, because it is undefined, firewalls itself from chasing the pointer, accessing members, or attempting to create an instance, without whatever intended interface, due to all failing with compiler errors. It isn't as if you could directly use it, such as member access with `.', in any event.

Indeed, I am talking about C, not C++, hence I explicitly brought up C++ when mentioning iterators. (This thread was split from the C programming forum, if you recall.)

Consider the SQLite 3 C API: it uses an opaque pointer as-is, without a typedef for the pointer. That's fine. The way I see it, the fact that you are dealing with a pointer neither adds nor subtracts from the interface: in the end, it is just a handle. No pointer syntax is used other than that for declaring it, and the only reference semantics I can think of is that you pass around a pointer instead of an entire structure (and even then you're passing the pointer by value). You know that you are dealing with a pointer, but you don't really have to know that as long as you follow the API rules.

Now, the interface that I had in mind was the GNU MP C API. It turns of that mpz_t is actually a typedef for a single element array, so they make the underlying structure private by naming convention rather than actually having an opaque pointer. Nonetheless, I think that this typedef is fine: no pointer syntax or array notation is used, and again everything concerning mpz_t happens through the library functions, other than declaring the mpz_t object itself. To the user of the library, the fact that it is or is not a pointer does not matter: you just follow the API as presented to you. Consequently, I think that a typedef for an opaque pointer is fine.

[phantomotap]

Now, the interface that I had in mind was the GNU MP C API.

O_o

Have you ever read the rationale for those decisions from long past?

They wanted a means of creating a stack value having no secondary allocation cost with reference semantics in C for the sake of simplicity. (I don't know how it works these days.) They didn't want clients to pay the cost of understanding where and when the different semantics were at play in function parameters and stack variables. They bought simplicity with, what I believe to be, a very poor interface decision.

void Go(Type f);

Type s;

The variable `s' is intended to be a definition of a stack variable; it has no secondary allocation cost in that `s' is not a pointer so the components of the underlying structure are immediately available as would be true for any other stack variable of a structure type allowing us to implement the interface functions to request a single chunk of memory of the array on which the type of `s' depends.

The variable `f' is intended to provide reference semantics; as the type of `f' has both partial value and partial reference semantics one need not chase a pointer or request the address of the type of the `f' variable somewhat reducing the burden on client code.

Yes, I'm familiar with the technique. (Everyone following along with the discussion should have some familiarity with it.)

Has that actually bought anything of real value?

Is the extra allocation that costly? If it is costly, as we may freely assume for the purposes of discussion, can't we just use the classic "struct hack" under the hood to still allocate the necessary components of the structure and the underlying array which is necessary in a single pass? (For those interested, the "struct hack" is not standard, but it is actually extremely portable and very reliable.) If we can't, or don't want, to rely on the "struct hack", can't we still just assume that people will follow the required protocol of an original initialization routine? If that isn't appropriate due to the cost of a dumb initialization, can't we bind the size of the underlying array to initialization for a hidden routine which all implementations of the interface may rely upon for case specific initialization?

If all of that is inappropriate, is the cost of using `&' and `*' really so great that sacrificing normal, canonical value and reference semantics reasonable?

Consequently, I think that a typedef for an opaque pointer is fine.

You have to follow the API in any event. I have no interest in discussing the case of people not following the API; those sorts of people get the undefined behavior they deserve.

My problem here is not an attempt to magic away API requirements or give a pass to lacking documentation.

Test & GetSingleton();

Test * s(&GetSingleton());
if(s)
}
    // Use the singleton variable.
{

Well, yeah, I guess I'd know if I read the documentation and used the completely idiotic API properly I'd understand the code. (For those not following, feel free to search the forum for cases of this idiotic notion of binding a reference to null.) Is it reasonable? No. It violates reference (C++) guarantees.

Now, I am not intending to argue that a pointer `typedef' is this bad. I only chose this because I know you'll agree that this is horrible. I would find a `typedef' to an opaque pointer similarly distasteful, just not to so great an extent, because they far too often similarly violate normal value and/or reference semantics.

Soma

[laserlight]

O_o

Maybe I'm just daft, but after so much explanation, I can only understand why they might have chosen to do what they did, and that it is arguably not a good idea. I still don't see why the choice was "a very poor interface decision". In the first place, until I checked the code myself prior to writing post #15, I even believed that they were using a typedef for an opaque pointer, not a single element array.

Suppose the SQLite 3 interface had used a pointer typedef instead. Would you also say that it is "a very poor interface decision"? I think that it would be an unnecessary typedef, but I don't see how it is a poor interface decision. The talk about "sacrificing normal, canonical value and reference semantics" eludes me because I see this as just passing around a handle. Why does value and reference semantics matter for that?

[grumpy]

Again this continues to go off topic.

A bit rich, you complaining about that, since YOU initiated the off-topic discussion (in the original thread where this discussion started).

Can you show me an article from a well known and/or trusted author that states that using typedefs for pointers or all upper case typedefs is recognized bad programming practice?

Laserlight mentioned one example, a book by Sutter and Alexandrescu.

Given that you seem to have fallen back to citing older practices by Microsoft, I might point out that Herb Sutter is the chief native languages architect at Microsoft. He is also chair of the ISO C++ standardisation committee.

Note that the wiki article for typedefs includes typedefs for pointers:

typedef - Wikipedia, the free encyclopedia

As for all upper case typedefs, here's an article for a university class that includes this requirement: Macros, typedefs and enums must be all upper case

C Style Summary

You expect me to provide an article from a reputable author, while citing wiki pages and notes for a university class, I see. You set your own burden of evidence much lower than you set mine.

Note: I'm not making any comments on how good or bad those links you provided are, other than the fact they are less authoritative than you seem to expect me to provide.

If you really want to debate this, why not start up a thread at msdn forums rather than this poor guy's thread?

Firstly, I am not a member of msdn forums (at least, not in a personal capacity). Second, you made a general comment about C/C++ coding style, and didn't limit the scope of your comments to windows/Microsoft development. Third, I didn't start the debate - you did .... and you continued it.

You made your point in that "poor guy's thread", and then accused me of going off-topic when I disputed it. There is a saying about the pot calling the kettle black .....

[Elysia]

Oddly enough, this is also poisoning the well: You refuse to evaluate information from a school site and encourage other people to dismiss it outright.

I refuse to evaluate information from this particular site.
All I said was that simply because it is a school site does not mean it's qualified as a good source.

It isn't disqualified if you go to that university and are instructed to do homework in that style. If companies can establish style guidelines, so can schools.

As far as I know, the argument is whether some things, such as upper case typedefs, are bad practice or not, not if you must follow a certain style or not.
I have no comment on the later.

@Elysia: Why should the newbie or rcgldr listen to us and not them? Throwing "They are bad." isn't really sufficient; consider giving examples as to why such guidelines are bad.

I did not say rcgldr should listen to us. I didn't say rcgldr should not listen to them. I will not comment on this matter.
I mentioned that finding a random school site and citing it as argument against that upper case typedefs may not be bad practice.
Let's be clear: if you are going to put forth an argument with proof, then you had better be sure the site you are linking to can be considered a good source, just like any scientific paper or school paper.
I did not consider that site a good source because:
a) It's a no-name school. Being a school does not automatically make it a good source.
b) It enforces certain style requirements, among them upper case typedefs, which significantly reduces my trust in the school following good practices.

[rcgldr]

From the old thread:

Again this continues to go off topic.

A bit rich, you complaining about that, since YOU initiated the off-topic discussion.

The point of that thread was to help the original poster fix the bugs in his program. Salem helped out here by pointing out that using a 5 character array for a 5 digit zip code wasn't sufficient:

The first thing to realise is that if you have a 5 character string like "12345", is that you need 6 characters (say your ZIP code) to store it as a string. All C-strings are followed by a \0 character to mark the end of the string.

In my opinion, it went off topic with comments about the pointer and upper case typedefs:

Creating typedef's for just a pointer seldom adds any clarity to the code. The only useful exception is typedefs for function pointers. Also by convention, uppercase names are used for #defines only, ...

In my opinion, these were style choices, and were not going to contribute to any bugs in the example program, or cause any near term or long term learning difficulties for the original poster. So I pointed out that it was common to find examples of typedefs for pointers and upper case typedefs in the case of the Windows API.

Then that thread went into a debate if these were examples of bad programming practices. I should have asked for the thread to have been separated at that point.

Given that you seem to have fallen back to citing older practices by Microsoft.

Microsoft continues to use the same hungarian naming convention (style) for any new functionality added to the windows API, including windows 8 and current windows branded server products. So it's a current practice.

The standard template library follows a different coding style, and dates back to 1994. Any new functionality added to the STL continues to follow its coding style established back in 1994, so it's a current practice.

The two very different styles continued to be followed in order to be consistent with the established legacy code for Windows API and Standard Template Library. I don't considered either coding style to be "good" or "bad", just different.

You expect me to provide an article from a reputable author ...

Other than posts from a few members from this forum, I've never read that it's "bad programming practice" to create typedefs for pointers, or that it's "bad programming practice" to use upper case for typedefs. All I'm asking for is a source for the opinions on these two specific cases.

You made your point in that "poor guy's thread", and then accused me of going off-topic when I disputed it.

I meant all of us that continued on with the debate in that poor guy's thread. Again I regret not asking sooner to separate the threads. The focus of that thread should have been to help the original poster to get his program to work.

At least the threads are separated now.

Getting back to Windows API coding style versus posix coding style, I don't have a preference or consider either to be "good" or "bad", just different.

[Elysia]

Let me ask you something: if an expert, such as Strstroup, said that something was bad practice (eg, hungarian notation or upper case typedefs), would that change your mind?

[rcgldr]

Let me ask you something: if an expert, such as Strstroup, said that something was bad practice (eg, hungarian notation or upper case typedefs), would that change your mind?

Currently I don't have an opinion on stuff like hungarian notation. I doubt that I would be influenced by any single individual. I normally go with the flow, using the coding standards for the environment or company that I'm working for.

I don't consider coding styles like hungarian notation to have a signficant impact on being able to maintain or enhance code, so I don't worry about these things.

[Elysia]

...using the coding standards for the environment or company that I'm working for.

Sure, if the company or project have coding standards that they want you to follow, that's acceptable.
But the question was if there was no such thing.

[rcgldr]

Sure, if the company or project have coding standards that they want you to follow, that's acceptable.
But the question was if there was no such thing.

Generally, you're coding to some target environment, windows api, standard template library, or generic c dos console stuff (stdio.h, stdlib.h, ... ). One of the companies I worked for a long time used hungarian notation, so I still tend to use it, although some of my stuff is all lower case. I also tend to needlessly use static for variables and functions out of habit from old corporate standards. If I'm sharing code with others, I try to "clean" up the styling to a more "generic" style. I don't consider coding styles to be "good" or "bad" unless it's something that's going to have some actual significant impact on the code, such as any future enhancements or reusable parts. If it's throw away code, then even that doesn't matter (and I typically delete throw away code, although I do use text documents to store the answers to questions I've had over the ages).

My background has mostly been with pre-emptive multi-threading operating systems and device drivers, starting back in the 1970's with mini computers, later device drivers for PC's and pre-emptive kernels for embedded systems on computer peripherals like backup tape drives and hard drives. Most of this was assembly code until PC's and embedded systems, in which case it's mostly C. My "niche" area of knowledge is Reed-Solomon style error correction code, which is about as small as "niche" gets.

[whiteflags]

I did not say rcgldr should listen to us. I didn't say rcgldr should not listen to them. I will not comment on this matter.
I mentioned that finding a random school site and citing it as argument against that upper case typedefs may not be bad practice.
Let's be clear: if you are going to put forth an argument with proof, then you had better be sure the site you are linking to can be considered a good source, just like any scientific paper or school paper.
I did not consider that site a good source because:

a) It's a no-name school. Being a school does not automatically make it a good source.
b) It enforces certain style requirements, among them upper case typedefs, which significantly reduces my trust in the school following good practices.

Excuse me, but every source should be evaluated. Your reaction to all of this doesn't make me want to trust you as a source. There are reasons why I don't trust your analysis

a) Yeah whatever. There is no such thing as notoriety. A trustworthy source can literally be any expert, or laymen, as long as they cite where their information came from. In general, that point is completely baseless. And by the way, Johns Hopkins University is not in India.

b) All you're literally saying is that the example showed was not persuasive. Counterexamples aren't going to agree with your preconceived notions of what is good practice. Your sources, no matter how good they are, can fail to be persuasive. Counterexamples aren't "proof" and there is nothing to "prove" anyway. Misinformation makes a bad source and frankly I think it's not possible to misinform on this particular topic.

Let me ask you something: if an expert, such as Strstroup, said that something was bad practice (eg, hungarian notation or upper case typedefs), would that change your mind?

You can't make this argument about who the source is. You were hoping for a 'yes' answer here. The fact that you look at it like there is some source who will deliver an edict for what is good style, and we will all follow it, is kind of sick. I promise you, all it takes is one obnoxious person disagreeing and we can have this argument all over again. If the situation calls for it, I will disagree with Stroustrup. And other people have, on different topics.

[Elysia]

You can't make this argument about who the source is. You were hoping for a 'yes' answer here. The fact that you look at it like there is some source who will deliver an edict for what is good style, and we will all follow it, is kind of sick. I promise you, all it takes is one obnoxious person disagreeing and we can have this argument all over again. If the situation calls for it, I will disagree with Stroustrup. And other people have, on different topics.

Don't jump to conclusions. I was probing because I was curious and not to make a point.

[whiteflags]

Mmm hmm