June 18th, 2008

MSDN-speak: What does it mean when a parameter contains a value?

I’ve seen some confusion over this, heck I’ve been confused by this, so I figured I’d share what I’ve learned. In MSDN, you may see wording like this:

pdwResult [out] When the function returns, contains a pointer to a DWORD value that contains the result of the computation.

What they’re trying to say is that the pdwResult is a pointer to a DWORD that receives the result of the computation. Personally, I take issue with both uses of the word “contains”, but they tell me that that is their standard for describing [out] parameters, so you’d better get used to it. When they say that the parameter contains a value, they mean that the you passed that value as the parameter. I prefer to think of the parameter being the value; the parameter is just a convenient name for the value that the caller passed. The MSDN approach is to think of the parameter as its own variable which therefore contains a value, as variables do. In this specific case, they are saying that pdwResult “contains a pointer” to mean that the parameter is itself a pointer that you pass in. Now on to the second half. When they say that the pointed-to value contains the result, they mean that the function itself writes to the pointed-to value. The opening phrase “when the function returns” is intended to indicate this, but I have two issues with that approach. First, it seems to modify the wrong verb. Since it’s at the beginning of the sentence, the temporal clause appears to modify the first “contains” and not the second. “When the function returns, the parameter contains a pointer…”, suggesting that perhaps when you initially called the function, the parameter didn’t contain the pointer and that the statement becomes true only when the function returns. Second, it doesn’t emphasize that the function itself sets the value. You can read the sentence passively, as if to say, “Well, when the function returns, there’s stuff there, who knows how it got there, maybe it was there all along, maybe you were expected to put it there first, sometimes things just happen to be that way, you know?” Sort of like, “When I get home, the lights are on.” Maybe you turned on the lights remotely from work before you left for home. Maybe they are on a timer so they turn on at the same time every day. Maybe they were on all day. Heck, you’re not even ruling out the possibility that the lights have psychic powers and turn themselves on as a way of welcoming you home.

Anyway, now you know what that sentence means when you read it in MSDN. It’s not how I would’ve written it, but I’m not the chief editor of MSDN.

Topics
Other

Author

Raymond has been involved in the evolution of Windows for more than 30 years. In 2003, he began a Web site known as The Old New Thing which has grown in popularity far beyond his wildest imagination, a development which still gives him the heebie-jeebies. The Web site spawned a book, coincidentally also titled The Old New Thing (Addison Wesley 2007). He occasionally appears on the Windows Dev Docs Twitter account to tell stories which convey no useful information.

0 comments

Discussion are closed.