Even if a function doesn't do anything, you still have to call it if the documentation says so, because it might do something tomorrow

re: Even if a function doesn't do anything, you still have to call it if the documentation says so, because it might do something tomorrow

640k — Wed, 01 Oct 2008 22:13:20 GMT

Windows APIs has a lot of magic, can't be sure about anything.

C functions which returns buffers are always tricky, easy to get it wrong both when implementing the api code and the application code.

"const" keyword doesn't compile to anything, and isn't enforced when executing.

re: Even if a function doesn't do anything, you still have to call it if the documentation says so, because it might do something tomorrow

James — Tue, 30 Sep 2008 05:17:06 GMT

You don't need to read every line of the manual in this case.

You have a function that returns a pointer (and a non-const one, no less). People with common sense should ask, "who owns the pointee, and if it's the caller's responsibility to free it, how does the caller do so?". You don't even need to look at the manual first to know to ask these questions; they're implied by the function signature.

A quick scan through the documentation should answer those questions.

But sadly, I admit that common sense is not nearly as common as it ought to be.

re: Even if a function doesn't do anything, you still have to call it if the documentation says so, because it might do something tomorrow

M1EK — Mon, 29 Sep 2008 23:21:08 GMT

Ding ding ding for Matt Craighead's answer.

Also, you don't need a time machine to identify that more than one party was to blame here. That doesn't change the solution now, but it does help us possibly avoid future problems of this type.

A programming API that requires that every programmer have read every single line of the manual to avoid dying in flames is not a good API. There was a time I felt differently, of course. I got better.

[You didn't have to read every single line of the manual. The information was right there in the documentation for GetEnvironmentStrings: "When the block returned by GetEnvironmentStrings is no longer needed, it should be freed by calling the FreeEnvironmentStrings function." And besides, when you call a function that returns some sort of resource, don't you naturally want to know "What do I do when I'm done with it?" -Raymond]

re: Even if a function doesn't do anything, you still have to call it if the documentation says so, because it might do something tomorrow

Matt Craighead — Mon, 29 Sep 2008 22:29:52 GMT

If we really want to criticize the API design in any detail, I would also point out that getting the entire environment block is very rarely what you want. Nor is the format of the environment block very application-friendly to parse, and there are plenty of opportunities for bugs there, too (can you say case sensitivity problems?).

I would rather keep the format and order of the environment block hidden (so you're free to change it -- what if you wanted to change it to a hash table or binary tree to increase performance?), and only provide getenv/setenv APIs. There is then the question of providing an environment block at process creation, but there, I expect you generally either want to (A) inherit everything or (B) build a new environment from scratch, selectively inheriting using getenv() if necessary.

re: Even if a function doesn't do anything, you still have to call it if the documentation says so, because it might do something tomorrow

fdiv — Mon, 29 Sep 2008 15:20:18 GMT

I never disassemble the Windows code to see what an API does and not just because the EULA forbids it. Most of the time either Raymond explains it, or I look at what Wine does and that often explains things.

re: Even if a function doesn't do anything, you still have to call it if the documentation says so, because it might do something tomorrow

SuperKoko — Sat, 27 Sep 2008 11:51:52 GMT

[Okay, you have a time machine. What do you do? Do you have the cleanup function do some pointless busy work just so it does "something"? -Raymond]

I don't think the implementation is flawed, but if I had a time machine I might take a very defensive approach: Counting resource references. Incrementing a process-wide counter when GetEnvironmentStrings is called and decreasing it when FreeEnvironmentStrings is called. If the count, when a process terminates or exit, is non-zero, this event would be logged.

However, its limit are obvious:

1) It doesn't prevent application from calling FreeEnvironmentStrings on the wrong pointer.

Adding testing logic is possible, but would necessarily GetEnvironmentStrings to copy the string.

(An instance ordinal would be added in the bytes preceding the string... People would obviously mess with it...)

2) Programmers would ignore the logs.

3) It is making the release version of Windows look like a debug version. Just because bad programmers don't use debugging tools, end users would suffer from performances of debugging tools.

@M1EK: So, are you telling us that the average programmer doesn't read the manual but disassemble the Windows code? I cannot believe that!

I would rather expect the bad programmer not to care about resource leaks as far as the memory leaks don't make his program crash in an "out of memory" condition afer 10 minutes, which is not likely to happen with little-used resources such as environment blocks and kernel handles.

"what would you have done at the time you created your first win32 window?"

I remember very well. I carefully read the SDK documentation and took an extremely defensive approach everywhere I wasn't sure... Of course, as I usually do, I freed resources in the reverse order of their allocation. Later, as I better knew the documentation, I relaxed my programming technique.

re: Even if a function doesn't do anything, you still have to call it if the documentation says so, because it might do something tomorrow

Sat, 27 Sep 2008 02:25:58 GMT

what would you have done at the time you created your first win32 window? i believe that you are now capable of using win32 correctly but only because you have gone through every misery unmanaged code has to offer at least once ;-) unfortunately many programmers are, after 10 years of experience, still at the entry level.

an api can be designed to help you and it can be designed without consciousness of usability. GetEnvironmentStrings one is of the latter (although the usability problem is only minor. there are other examples as well).

re: Even if a function doesn't do anything, you still have to call it if the documentation says so, because it might do something tomorrow

Duke of New York — Sat, 27 Sep 2008 02:01:59 GMT

The name of the API is "GetEnvironmentStrings." Its job, believe it or not, is to get environment strings and then let the application move on-- not to anticipate whether you need a copy, how many, for how long, from which allocators, etc., etc. All of those are things the application can manage for itself, using other APIs, or no APIs.

re: Even if a function doesn't do anything, you still have to call it if the documentation says so, because it might do something tomorrow

Sat, 27 Sep 2008 01:50:22 GMT

"Then the app is ignoring the part of the documentation that says"

this is constantly happening. after all, this blog is partially about the phenomenon of bad code. as a systems designer you cannot ignore this. i even have to think about it when coworkers are using my code!

"If you need a copy for applications-specific reasons, make a copy. It's not the operating system's job to write your application for you."

of course it is! the operating system provides services to you in order to alleviate the need for implementing them yourself. the reason for choosing a development platform is that one platform might reduce your work more than the other.

re: Even if a function doesn't do anything, you still have to call it if the documentation says so, because it might do something tomorrow

Duke of New York — Sat, 27 Sep 2008 01:44:49 GMT

"what if the app decides to use the returned buffer as some kind of working memory an does string operations in it?"

Then the app is ignoring the part of the documentation that says:

"Treat this memory as read-only"

Aside from that, the end-to-end principle applies. If you need a copy for applications-specific reasons, make a copy. It's not the operating system's job to write your application for you.